idnits 2.17.1 draft-ietf-tictoc-1588v2-yang-07.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 (November 28, 2017) is 2333 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) ** 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 (~~), 2 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: May 2018 November 28, 2017 11 YANG Data Model for IEEE 1588-2008 12 draft-ietf-tictoc-1588v2-yang-07 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 May 28, 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 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 203 Structured attributes of clocks (an OC, BC or TC) used for 204 PTP protocol decisions and for providing values for PTP 205 message fields, see Section 8 of [IEEE1588]. 207 PTP instance 208 A PTP implementation in the device (i.e., an OC or BC) 209 represented by a specific PTP dataset. 211 2. IEEE 1588-2008 YANG Model hierarchy 213 This section describes the hierarchy of an IEEE 1588-2008 YANG 214 module. Query and configuration of device wide or port specific 215 configuration information and clock data set are described for this 216 version. 218 Query and configuration of clock information include: 220 (Note: The attribute names are consistent with IEEE 1588-2008, but 221 changed to the YANG style, i.e., using all lower-case, with dashes 222 between words.) 224 - Clock data set attributes in a clock node, including: current-ds, 225 parent-ds, default-ds, time-properties-ds, and transparent-clock- 226 default-ds. 228 - Port-specific data set attributes, including: port-ds and 229 transparent-clock-port-ds. 231 The readers are assumed to be familiar with IEEE 1588-2008. As all 232 PTP terminologies and PTP data set attributes are described in 233 details in IEEE 1588-2008 [IEEE1588], this document only outlines 234 each of them in the YANG module. 236 A simplified graphical representation of the data model is 237 typically used by YANG modules as described in [RFC8040]. This 238 document uses the same representation and the meaning of the 239 symbols in these diagrams is as follows: 241 o Brackets "[" and "]" enclose list keys. 243 o Abbreviations before data node names: "rw" means configuration 244 data (read-write) and "ro" state data (read-only). For IEEE 1588- 245 2008, all data nodes are marked "rw" (see 2.2). 247 o Symbols after data node names: "?" means an optional node, "!" 248 means a presence container, and "*" denotes a list and leaf-list. 250 o Parentheses enclose choice and case nodes, and case nodes are 251 also marked with a colon (":"). 253 o Ellipsis ("...") stands for contents of subtrees that are not 254 shown. 256 o Arrow ("->") stands for a reference to a particular leaf 257 instance in the tree. 259 module: ietf-ptp 260 +--rw ptp 261 +--rw instance-list* [instance-number] 262 | +--rw instance-number uint32 263 | +--rw default-ds 264 | | +--rw two-step-flag? boolean 265 | | +--rw clock-identity? clock-identity-type 266 | | +--rw number-ports? uint16 267 | | +--rw clock-quality 268 | | | +--rw clock-class? uint8 269 | | | +--rw clock-accuracy? uint8 270 | | | +--rw offset-scaled-log-variance? uint16 271 | | +--rw priority1? uint8 272 | | +--rw priority2? uint8 273 | | +--rw domain-number? uint8 274 | | +--rw slave-only? boolean 275 | +--rw current-ds 276 | | +--rw steps-removed? uint16 277 | | +--rw offset-from-master? time-interval-type 278 | | +--rw mean-path-delay? time-interval-type 279 | +--rw parent-ds 280 | | +--rw parent-port-identity 281 | | | +--rw clock-identity? clock-identity-type 282 | | | +--rw port-number? uint16 283 | | +--rw parent-stats? boolean 284 | | +--rw observed-parent-offset-scaled-log-variance? uint16 285 | | +--rw observed-parent-clock-phase-change-rate? int32 286 | | +--rw grandmaster-identity? binary 287 | | +--rw grandmaster-clock-quality 288 | | | +--rw clock-class? uint8 289 | | | +--rw clock-accuracy? uint8 290 | | | +--rw offset-scaled-log-variance? uint16 291 | | +--rw grandmaster-priority1? uint8 292 | | +--rw grandmaster-priority2? uint8 293 | +--rw time-properties-ds 294 | | +--rw current-utc-offset-valid? boolean 295 | | +--rw current-utc-offset? int16 296 | | +--rw leap59? boolean 297 | | +--rw leap61? boolean 298 | | +--rw time-traceable? boolean 299 | | +--rw frequency-traceable? boolean 300 | | +--rw ptp-timescale? boolean 301 | | +--rw time-source? uint8 302 | +--rw port-ds-list* [port-number] 303 | +--rw port-number uint16 304 | +--rw port-state? port-state-enumeration 305 | +--rw underlying-interface? if:interface-ref 306 | +--rw log-min-delay-req-interval? int8 307 | +--rw peer-mean-path-delay? time-interval-type 308 | +--rw log-announce-interval? int8 309 | +--rw announce-receipt-timeout? uint8 310 | +--rw log-sync-interval? int8 311 | +--rw delay-mechanism? delay-mechanism-enumeration 312 | +--rw log-min-pdelay-req-interval? int8 313 | +--rw version-number? uint8 314 +--rw transparent-clock-default-ds 315 | +--rw clock-identity? clock-identity-type 316 | +--rw number-ports? uint16 317 | +--rw delay-mechanism? delay-mechanism-enumeration 318 | +--rw primary-domain? uint8 319 +--rw transparent-clock-port-ds-list* [port-number] 320 +--rw port-number uint16 321 +--rw clock-identity? clock-identity-type 322 +--rw log-min-pdelay-req-interval? int8 323 +--rw faulty-flag? boolean 324 +--rw peer-mean-path-delay? time-interval-type 326 2.1. Interpretations from IEEE 1588 Working Group 328 The preceding model and the associated YANG module have some subtle 329 differences from the data set specifications of IEEE Std 1588-2008. 330 These differences are based on interpretation from the IEEE 1588 331 Working Group, and are intended to provide compatibility with 332 future revisions of the IEEE 1588 standard. 334 In IEEE Std 1588-2008, a physical product can implement multiple 335 PTP clocks (i.e. ordinary, boundary, or transparent clock). As 336 specified in 1588-2008 subclause 7.1, each of the multiple clocks 337 operates in an independent domain. However, the organization of 338 multiple PTP domains was not clear in the data sets of IEEE Std 339 1588-2008. This document introduces the concept of PTP instance as 340 described in the new revision of IEEE 1588. The instance concept is 341 used exclusively to allow for optional support of multiple domains. 342 The instance number has no usage within PTP messages. 344 Based on statements in IEEE 1588-2008 subclauses 8.3.1 and 10.1, 345 most transparent clock products have interpreted the transparent 346 clock data sets to reside as a singleton at the root level of the 347 managed product, and this YANG model reflects that location. 349 2.2. Configuration and state 351 The information model of IEEE Std 1588-2008 classifies each member 352 in PTP data sets as one of the following: 354 - Configurable: Writable by management. 356 - Dynamic: Read-only to management, and the value is changed by 357 1588 protocol operation. 359 - Static: Read-only to management, and the value typically does not 360 change. 362 Under certain circumstances, the classification of an IEEE 1588 363 data set member can change. For details on the classification of 364 each PTP data set member, refer to the IEEE Std 1588-2008 365 specification for that member. 367 3. IEEE 1588-2008 YANG Module 369 This module imports typedefs from [RFC7223]. Most attribute names 370 are based on the information model defined in [IEEE1588], but 371 adapted to the YANG style of naming. 373 file "ietf-ptp@2017-11-28.yang" 375 module ietf-ptp { 376 namespace "urn:ietf:params:xml:ns:yang:ietf-ptp"; 377 prefix "ptp"; 379 import ietf-interfaces { 380 prefix if; 381 } 383 organization "IETF TICTOC Working Group"; 384 contact 385 "WG Web: http://tools.ietf.org/wg/tictoc/ 386 WG List: 387 WG Chair: Karen O'Donoghue 388 389 WG Chair: Yaakov Stein 390 391 Editor: Yuanlong Jiang 392 393 Editor: Rodney Cummings 394 "; 395 description 396 "This YANG module defines a data model for the configuration 397 of IEEE 1588-2008 clocks, and also for retrieval of the state 398 data of IEEE 1588-2008 clocks."; 400 revision "2017-11-28" { 401 description "Version 7.0"; 402 reference "draft-ietf-tictoc-1588v2-yang"; 403 } 405 typedef delay-mechanism-enumeration { 406 type enumeration { 407 enum e2e { 408 value 1; 409 description 410 "The port uses the delay request-response mechanism."; 411 } 412 enum p2p { 413 value 2; 414 description 415 "The port uses the peer delay mechanism."; 416 } 417 enum disabled { 418 value 254; 419 description 420 "The port does not implement any delay mechanism."; 421 } 422 } 423 description 424 "The propagation delay measuring option used by the 425 port. Values for this enumeration are specified 426 by the IEEE 1588 standard exclusively."; 427 reference 428 "IEEE Std 1588-2008: 8.2.5.4.4"; 429 } 431 typedef port-state-enumeration { 432 type enumeration { 433 enum initializing { 434 value 1; 435 description 436 "The port is initializing its data sets, hardware, and 437 communication facilities."; 438 } 439 enum faulty { 440 value 2; 441 description 442 "The port is in the fault state."; 443 } 444 enum disabled { 445 value 3; 446 description 447 "The port is disabled, and is not communicating PTP 448 messages (other than possibly PTP management 449 messages)."; 450 } 451 enum listening { 452 value 4; 453 description 454 "The port is listening for an Announce message."; 455 } 456 enum pre-master { 457 value 5; 458 description 459 "The port is in the pre-master state."; 460 } 461 enum master { 462 value 6; 463 description 464 "The port is behaving as a master port."; 465 } 466 enum passive { 467 value 7; 468 description 469 "The port is in the passive state."; 470 } 471 enum uncalibrated { 472 value 8; 473 description 474 "A master port has been selected, but the port is still 475 in the uncalibrated state."; 476 } 477 enum slave { 478 value 9; 479 description 480 "The port is synchronizing to the selected master port."; 481 } 482 } 484 description 485 "The current state of the protocol engine associated 486 with the port. Values for this enumeration are specified 487 by the IEEE 1588 standard exclusively."; 488 reference 489 "IEEE Std 1588-2008: 8.2.5.3.1, 9.2.5"; 490 } 492 typedef time-interval-type { 493 type int64; 494 description 495 "Derived data type for time interval, represented in units of 496 nanoseconds and multiplied by 2^16"; 497 reference 498 "IEEE Std 1588-2008: 5.3.2"; 499 } 501 typedef clock-identity-type { 502 type binary { 503 length "8"; 504 } 505 description 506 "Derived data type to identify a clock"; 507 reference 508 "IEEE Std 1588-2008: 5.3.4"; 509 } 511 grouping clock-quality-grouping { 512 description 513 "Derived data type for quality of a clock, which contains 514 clockClass, clockAccuracy and offsetScaledLogVariance."; 515 reference 516 "IEEE Std 1588-2008: 5.3.7"; 518 leaf clock-class { 519 type uint8; 520 default 248; 521 description 522 "The clockClass denotes the traceability of the time 523 or frequency distributed by the clock."; 524 } 526 leaf clock-accuracy { 527 type uint8; 528 description 529 "The clockAccuracy indicates the expected accuracy 530 of the clock."; 531 } 533 leaf offset-scaled-log-variance { 534 type uint16; 535 description 536 "The offsetScaledLogVariance provides an estimate of 537 the variations of the clock from a linear timescale 538 when it is not synchronized to another clock 539 using the protocol."; 540 } 541 } 543 container ptp { 544 description 545 "The PTP struct containing all attributes of PTP Dataset, 546 other optional PTP attributes can be augmented as well."; 548 list instance-list { 550 key "instance-number"; 552 description 553 "List of one or more PTP datasets in the device (see IEEE 554 Std 1588-2008 subclause 6.3). 555 Each PTP dataset represents a distinct instance of 556 PTP implementation in the device (i.e. distinct 557 Ordinary Clock or Boundary Clock)."; 559 leaf instance-number { 560 type uint32; 561 description 562 "The instance number of the current PTP instance. 563 This instance number is used for management purposes 564 only. This instance number does not represent the PTP 565 domain number, and is not used in PTP messages."; 566 } 568 container default-ds { 569 description 570 "The default data set of the clock (see IEEE Std 571 1588-2008 subclause 8.2.1)."; 573 leaf two-step-flag { 574 type boolean; 575 description 576 "When set, the clock is a two-step clock; otherwise, 577 the clock is a one-step clock."; 578 } 580 leaf clock-identity { 581 type clock-identity-type; 582 description 583 "The clockIdentity of the local clock"; 584 } 586 leaf number-ports { 587 type uint16; 588 description 589 "The number of PTP ports on the instance."; 590 } 592 container clock-quality { 593 description 594 "The clockQuality of the local clock."; 596 uses clock-quality-grouping; 597 } 599 leaf priority1 { 600 type uint8; 601 description 602 "The priority1 attribute of the local clock."; 603 } 605 leaf priority2{ 606 type uint8; 607 description 608 "The priority2 attribute of the local clock. "; 609 } 611 leaf domain-number { 612 type uint8; 613 description 614 "The domain number of the current syntonization 615 domain."; 616 } 618 leaf slave-only { 619 type boolean; 620 description 621 "When set, the clock is a slave-only clock."; 622 } 624 } 626 container current-ds { 627 description 628 "The current data set of the clock (see IEEE Std 629 1588-2008 subclause 8.2.2)."; 631 leaf steps-removed { 632 type uint16; 633 default 0; 634 description 635 "The number of communication paths traversed 636 between the local clock and the grandmaster clock."; 637 } 639 leaf offset-from-master { 640 type time-interval-type; 641 description 642 "The current value of the time difference between 643 a master and a slave clock as computed by the slave."; 644 } 646 leaf mean-path-delay { 647 type time-interval-type; 648 description 649 "The current value of the mean propagation time between 650 a master and a slave clock as computed by the slave."; 652 } 654 } 656 container parent-ds { 657 description 658 "The parent data set of the clock (see IEEE Std 1588-2008 659 subclause 8.2.3)."; 661 container parent-port-identity { 662 description 663 "The portIdentity of the port on the master, it 664 contains two members: clockIdentity and portNumber."; 665 reference 666 "IEEE Std 1588-2008: 5.3.5"; 668 leaf clock-identity { 669 type clock-identity-type; 670 description 671 "Identity of the clock"; 672 } 674 leaf port-number { 675 type uint16; 676 description 677 "Port number"; 678 } 679 } 681 leaf parent-stats { 682 type boolean; 683 default false; 684 description 685 "When set, the values of 686 observedParentOffsetScaledLogVariance and 687 observedParentClockPhaseChangeRate of parentDS 688 have been measured and are valid."; 689 } 691 leaf observed-parent-offset-scaled-log-variance { 692 type uint16; 693 default 65535; 694 description 695 "An estimate of the parent clock's PTP variance 696 as observed by the slave clock."; 697 } 699 leaf observed-parent-clock-phase-change-rate { 700 type int32; 701 description 702 "An estimate of the parent clock's phase change rate 703 as observed by the slave clock."; 704 } 706 leaf grandmaster-identity { 707 type binary { 708 length "8"; 709 } 710 description 711 "The clockIdentity attribute of the grandmaster clock."; 712 } 714 container grandmaster-clock-quality { 715 description 716 "The clockQuality of the grandmaster clock."; 717 uses clock-quality-grouping; 718 } 720 leaf grandmaster-priority1 { 721 type uint8; 722 description 723 "The priority1 attribute of the grandmaster clock."; 724 } 726 leaf grandmaster-priority2 { 727 type uint8; 728 description 729 "The priority2 attribute of the grandmaster clock."; 730 } 732 } 734 container time-properties-ds { 735 description 736 "The timeProperties data set of the clock (see 737 IEEE Std 1588-2008 subclause 8.2.4)."; 739 leaf current-utc-offset-valid { 740 type boolean; 741 description 742 "When set, the current UTC offset is valid."; 743 } 745 leaf current-utc-offset { 746 type int16; 747 description 748 "The offset between TAI and UTC when the epoch of the 749 PTP system is the PTP epoch, i.e., when ptp-timescale 750 is TRUE; otherwise, the value has no meaning."; 751 } 753 leaf leap59 { 754 type boolean; 755 description 756 "When set, the last minute of the current UTC day 757 contains 59 seconds."; 758 } 760 leaf leap61 { 761 type boolean; 762 description 763 "When set, the last minute of the current UTC day 764 contains 61 seconds."; 765 } 767 leaf time-traceable { 768 type boolean; 769 description 770 "When set, the timescale and the currentUtcOffset are 771 traceable to a primary reference."; 772 } 774 leaf frequency-traceable { 775 type boolean; 776 description 777 "When set, the frequency determining the timescale 778 is traceable to a primary reference."; 779 } 781 leaf ptp-timescale { 782 type boolean; 783 description 784 "When set, the clock timescale of the grandmaster 785 clock is PTP; otherwise, the timescale is ARB 786 (arbitrary)."; 787 } 788 leaf time-source { 789 type uint8; 790 description 791 "The source of time used by the grandmaster clock."; 792 } 793 } 795 list port-ds-list { 796 key "port-number"; 797 description 798 "List of port data sets of the clock (see IEEE Std 799 1588-2008 subclause 8.2.5)."; 801 leaf port-number{ 802 type uint16; 803 description 804 "Port number. 805 The data sets (i.e. information model) of IEEE Std 806 1588-2008 specify a member portDS.portIdentity, which 807 uses a typed struct with members clockIdentity and 808 portNumber. 810 In this YANG data model, portIdentity is not modeled 811 in the port-ds-list, however, its members are provided 812 as follows: 813 portIdentity.portNumber is provided as this port- 814 number leaf in port-ds-list; and 815 portIdentity.clockIdentity is provided as the clock- 816 identity leaf in default-ds of the instance 817 (i.e. ../../default-ds /clock-identity)."; 818 } 820 leaf port-state { 821 type port-state-enumeration; 822 default "initializing"; 823 description 824 "Current state associated with the port."; 825 } 827 leaf underlying-interface { 828 type if:interface-ref; 829 description 830 "Reference to the configured underlying interface that 831 is used by this PTP Port (see RFC 7223)."; 832 } 833 leaf log-min-delay-req-interval { 834 type int8; 835 description 836 "The base-two logarithm of the minDelayReqInterval 837 (the minimum permitted mean time interval between 838 successive Delay_Req messages)."; 839 } 841 leaf peer-mean-path-delay { 842 type time-interval-type; 843 default 0; 844 description 845 "An estimate of the current one-way propagation delay 846 on the link when the delayMechanism is P2P; otherwise, 847 it is zero."; 848 } 850 leaf log-announce-interval { 851 type int8; 852 description 853 "The base-two logarithm of the mean 854 announceInterval (mean time interval between 855 successive Announce messages)."; 856 } 858 leaf announce-receipt-timeout { 859 type uint8; 860 description 861 "The number of announceInterval that have to pass 862 without receipt of an Announce message before the 863 occurrence of the event ANNOUNCE_RECEIPT_TIMEOUT_ 864 EXPIRES."; 865 } 867 leaf log-sync-interval { 868 type int8; 869 description 870 "The base-two logarithm of the mean SyncInterval 871 for multicast messages. The rates for unicast 872 transmissions are negotiated separately on a per port 873 basis and are not constrained by this attribute."; 874 } 876 leaf delay-mechanism { 877 type delay-mechanism-enumeration; 878 description 879 "The propagation delay measuring option used by the 880 port in computing meanPathDelay."; 881 } 883 leaf log-min-pdelay-req-interval { 884 type int8; 885 description 886 "The base-two logarithm of the 887 minPdelayReqInterval (minimum permitted mean time 888 interval between successive Pdelay_Req messages)."; 890 } 892 leaf version-number { 893 type uint8; 894 description 895 "The PTP version in use on the port."; 896 } 898 } 899 } 901 container transparent-clock-default-ds { 902 description 903 "The members of the transparentClockDefault Data Set (see 904 IEEE Std 1588-2008 subclause 8.3.2)."; 906 leaf clock-identity { 907 type clock-identity-type; 908 description 909 "The clockIdentity of the transparent clock."; 910 } 912 leaf number-ports { 913 type uint16; 914 description 915 "The number of PTP ports on the Transparent Clock."; 916 } 918 leaf delay-mechanism { 919 type delay-mechanism-enumeration; 920 description 921 "The propagation delay measuring option 922 used by the transparent clock."; 923 } 925 leaf primary-domain { 926 type uint8; 927 default 0; 928 description 929 "The domainNumber of the primary syntonization domain."; 930 } 931 } 932 list transparent-clock-port-ds-list { 933 key "port-number"; 934 description 935 "List of transparentClockPort data sets of the transparent 936 clock (see IEEE Std 1588-2008 subclause 8.3.3)."; 938 leaf port-number { 939 type uint16; 940 description 941 "Port number. 942 The data sets (i.e. information model) of IEEE Std 943 1588-2008 specify a member 944 transparentClockPortDS.portIdentity, which uses a typed 945 struct with members clockIdentity and portNumber. 947 In this YANG data model, portIdentity is not modeled in 948 the transparent-clock-port-ds-list, however, 949 portIdentity.portNumber is provided as this leaf member 950 in transparent-clock-port-ds-list."; 952 } 954 leaf clock-identity { 955 type clock-identity-type; 956 description 957 "clock-identity. 958 The data sets (i.e. information model) of IEEE Std 959 1588-2008 specify a member 960 transparentClockPortDS.portIdentity, which uses a typed 961 struct with members clockIdentity and portNumber. 963 In this YANG data model, portIdentity is not modeled in 964 the transparent-clock-port-ds-list, however, 965 portIdentity.clockIdentity is provided as this leaf 966 member in transparent-clock-port-ds-list."; 967 } 969 leaf log-min-pdelay-req-interval { 970 type int8; 971 description 972 "The logarithm to the base 2 of the 973 minPdelayReqInterval (minimum permitted mean time 974 interval between successive Pdelay_Req messages)."; 975 } 977 leaf faulty-flag { 978 type boolean; 979 default false; 980 description 981 "When set, the port is faulty."; 982 } 984 leaf peer-mean-path-delay { 985 type time-interval-type; 986 default 0; 987 description 988 "An estimate of the current one-way propagation delay 989 on the link when the delayMechanism is P2P; otherwise, 990 it is zero."; 991 } 993 } 994 } 995 } 997 999 4. Security Considerations 1001 YANG modules are designed to be accessed via the NETCONF protocol 1002 [RFC6241], thus security considerations in [RFC6241] apply here. 1003 Security measures such as using the NETCONF over SSH [RFC6242] and 1004 restricting its use with access control [RFC6536] can further 1005 improve its security, avoid injection attacks and misuse of the 1006 protocol. Furthermore, general security considerations of time 1007 protocols are discussed in [RFC7384]. 1009 Some data nodes defined in this YANG module are writable, and an 1010 inappropriate use of them may adversely impact a synchronization 1011 network. For example, loss of synchronization on a clock, accuracy 1012 degradation on a set of clocks, or even break down of a whole 1013 synchronization network. 1015 5. IANA Considerations 1017 This document registers a URI in the IETF XML registry, and the 1018 following registration is requested to be made: 1019 URI: urn:ietf:params:xml:ns:yang:ietf-ptp 1021 This document registers a YANG module in the YANG Module Names: 1022 name: ietf-ptp namespace: urn:ietf:params:xml:ns:yang:ietf-ptp 1024 6. References 1026 6.1. Normative References 1028 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1029 Requirement Levels", BCP 14, RFC 2119, March 1997 1031 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1032 Network Configuration Protocol (NETCONF) ", RFC 6020, 1033 October 2010 1035 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1036 July 2013 1038 [RFC7223] Bjorklund, M., "A YANG Data Model for Interface 1039 Management", RFC 7223, May 2014 1041 [IEEE1588] IEEE, "IEEE Standard for a Precision Clock 1042 Synchronization Protocol for Networked Measurement and 1043 Control Systems", IEEE Std 1588-2008, July 2008 1045 6.2. Informative References 1047 [IEEE8021AS] IEEE, "Timing and Synchronizations for Time-Sensitive 1048 Applications in Bridged Local Area Networks", IEEE 1049 802.1AS-2001, 2011 1051 [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between 1052 Information Models and Data Models", RFC 3444, January 1053 2003 1055 [RFC4663] Harrington, D., "Transferring MIB Work from IETF Bridge 1056 MIB WG to IEEE 802.1 WG", RFC 4663, September 2006 1058 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 1059 Bierman, "Network Configuration Protocol (NETCONF)", RFC 1060 6241, June 2011 1062 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1063 Shell (SSH)", RFC 6242, June 2011 1065 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 1066 Protocol (NETCONF) Access Control Model", RFC 6536, March 1067 2012 1069 [RFC7384] Mizrahi, T., "Security Requirements of Time Protocols in 1070 Packet Switched Networks", RFC 7384, October 2014 1072 [RFC8040] Bierman, A., Bjorklund, M., and Watsen, K., "RESTCONF 1073 protocol", RFC 8040, January 2017 1075 [RFC8173] Shankarkumar, V., Montini, L., Frost, T., and Dowd, G., 1076 "Precision Time Protocol Version 2 (PTPv2) Management 1077 Information Base", RFC 8173, June 2017 1079 7. Acknowledgments 1081 The authors would like to thank Joe Gwinn, Mahesh Jethanandani, Tal 1082 Mizrahi, Opher Ronen, Liang Geng, Alex Campbell, Tom Petch and John 1083 Fletcher for their valuable reviews and suggestions, and thank 1084 Benoit Claise and Radek Krejci for their validation of the YANG 1085 module. 1087 Appendix A Transferring YANG Work to IEEE 1588 WG (Informational) 1089 This appendix describes a future plan to transition responsibility 1090 for IEEE 1588 YANG modules from the IETF TICTOC Working Group (WG) 1091 to the IEEE 1588 WG, which develops the time synchronization 1092 technology that the YANG modules are designed to manage. 1094 This appendix is forward-looking with regard to future 1095 standardization roadmaps in IETF and IEEE. Since those roadmaps 1096 cannot be predicted with significant accuracy, this appendix is 1097 informational, and it does not specify imperatives or normative 1098 specifications of any kind. 1100 The IEEE 1588-2008 YANG module of this standard represents a 1101 cooperation between IETF (for YANG) and IEEE (for 1588). For the 1102 initial standardization of IEEE-1588 YANG modules, the information 1103 model is relatively clear (i.e. IEEE 1588 data sets), but expertise 1104 in YANG is required, making IETF an appropriate location for the 1105 standards. The TICTOC WG has expertise with IEEE 1588, making it 1106 the appropriate location within IETF. 1108 The IEEE 1588 WG anticipates future changes to its standard on an 1109 ongoing basis. As IEEE 1588 WG members gain practical expertise 1110 with YANG, the IEEE 1588 WG will become more appropriate for 1111 standardization of its YANG modules. As the IEEE 1588 standard is 1112 revised and/or amended, IEEE 1588 members can more effectively 1113 synchronize the revision of this YANG module with future versions 1114 of the IEEE 1588 standard. 1116 This appendix is meant to establish some clear expectations between 1117 IETF and IEEE about the future transfer of IEEE 1588 YANG modules 1118 to the IEEE 1588 WG. The goal is to assist in making the future 1119 transfer as smooth as possible. As the transfer takes place, some 1120 case-by-case situations are likely to arise, which can be handled 1121 by discussion on the IETF TICTOC WG mailing lists and/or 1122 appropriate liaisons. 1124 This appendix obtained insight from [RFC4663], an informational 1125 memo that described a similar transfer of MIB work from the IETF 1126 Bridge MIB WG to the IEEE 802.1 WG. 1128 A.1. Assumptions for the Transfer 1130 For the purposes of discussion in this appendix, assume that the 1131 IETF TICTOC WG has approved a standard YANG module for a published 1132 IEEE 1588 standard. As of this writing, this is IEEE Std 1588-2008, 1133 but it is possible that YANG for subsequent 1588 revisions could be 1134 published from the IETF TICTOC WG. For discussion in this appendix, 1135 we use the phrase "last IETF 1588 YANG" to refer to most recently 1136 published 1588 YANG from the IETF TICTOC WG. 1138 The IEEE-SA Standards Board New Standards Committee (NesCom) 1139 handles new Project Authorization Requests (PARs) (see 1140 http://standards.ieee.org/board/nes/). PARs are roughly the 1141 equivalent of IETF Working Group Charters and include information 1142 concerning the scope, purpose, and justification for 1143 standardization projects. 1145 Assume that IEEE 1588 has an approved PAR that explicitly specifies 1146 development of a YANG module. The transfer of YANG work will occur 1147 in the context of this IEEE 1588 PAR. For discussion in this 1148 appendix, we use the phrase "first IEEE 1588 YANG" to refer to the 1149 first IEEE 1588 standard for YANG. 1151 Assume that as part of the transfer of YANG work, the IETF TICTOC 1152 WG agrees to cease all work on standard YANG modules for IEEE 1588. 1154 Assume that the IEEE 1588 WG has participated in the development of 1155 the last IETF 1588 YANG module, such that the first IEEE 1588 YANG 1156 module will effectively be a revision of it. In other words, the 1157 transfer of YANG work will be relatively clean. 1159 The actual conditions for the future transfer can be such that the 1160 preceding assumptions do not hold. Exceptions to the assumptions 1161 will need to be addressed on a case-by-case basis at the time of 1162 the transfer. This appendix describes topics that can be addressed 1163 based on the preceding assumptions. 1165 A.2. Intellectual Property Considerations 1167 During review of the legal issues associated with transferring 1168 Bridge MIB WG documents to the IEEE 802.1 WG (Section 3.1 and 1169 Section 9 of [RFC4663]), it was concluded that the IETF does not 1170 have sufficient legal authority to make the transfer to IEEE 1171 without the consent of the document authors. 1173 If the last IETF 1588 YANG is published as a RFC, the work is 1174 required to be transferred from the IETF to the IEEE, so that IEEE 1175 1588 WG can begin working on the first IEEE 1588 YANG. 1177 When work on the first IEEE YANG module begins in the IEEE 1588 WG, 1178 that work derives from the last IETF YANG module of this RFC, 1179 requiring a transfer of that work from the IETF to the IEEE. In 1180 order to avoid having the transfer of that work be dependent on the 1181 availability of this RFC's authors at the time of its publication, 1182 the IEEE Standards Association department of Risk Management and 1183 Licensing provided the appropriate forms and mechanisms for this 1184 document's authors to assign a non-exclusive license for IEEE to 1185 create derivative works from this document. Those IEEE forms and 1186 mechanisms will be updated as needed during the development of this 1187 document and any future IETF YANG modules for IEEE 1588. This will 1188 help to make the future transfer of work from IETF to IEEE occur as 1189 smoothly as possible. 1191 As stated in the initial "Status of this Memo", the YANG module in 1192 this document conforms to the provisions of BCP 78. The IETF will 1193 retain all the rights granted at the time of publication in the 1194 published RFCs. 1196 A.3. Namespace and Module Name 1198 As specified in the "IANA Considerations" section, the YANG module 1199 in this document uses IETF as the root of its URN namespace and 1200 YANG module name. 1202 Use of IETF as the root of these names implies that the YANG module 1203 is standardized in a Working Group of IETF, using the IETF 1204 processes. If the IEEE 1588 Working Group were to continue using 1205 these names rooted in IETF, the IEEE 1588 YANG standardization 1206 would need to continue in the IETF. The goal of transferring the 1207 YANG work is to avoid this sort of dependency between standards 1208 organizations. 1210 IEEE 802 has an active PAR (IEEE P802d) for creating a URN 1211 namespace for IEEE use (see 1212 http://standards.ieee.org/develop/project/802d.html). It is likely 1213 that this IEEE 802 PAR will be approved and published prior to the 1214 transfer of YANG work to the IEEE 1588 WG. If so, the IEEE 1588 WG 1215 can use the IEEE URN namespace for the first IEEE 1588 YANG module, 1216 such as: 1218 urn:ieee:Std:1588:yang:ieee1588-ptp 1220 where "ieee1588-ptp" is the registered YANG module name in the IEEE. 1222 Under the assumptions of section A.1, the first IEEE 1588 YANG 1223 module prefix can be the same as the last IETF 1588 YANG module 1224 prefix (i.e. "ptp"), since the nodes within both YANG modules are 1225 compatible. 1227 The result of these name changes are that for complete 1228 compatibility, a server (i.e. IEEE 1588 node) can choose to 1229 implement a YANG module for the last IETF 1588 YANG module (with 1230 IETF root) as well as the first IEEE 1588 YANG module (with IEEE 1231 root). Since the content of the YANG module transferred are the 1232 same, the server implementation is effectively common for both. 1234 From a client's perspective, a client of the last IETF 1588 YANG 1235 module (or earlier) looks for the IETF-rooted module name; and a 1236 client of the first IEEE 1588 YANG module (or later) looks for the 1237 IEEE-rooted module name. 1239 A.4. IEEE 1588 YANG Modules in ASCII Format 1241 Although IEEE 1588 can certainly decide to publish YANG modules 1242 only in the PDF format that they use for their standard documents, 1243 without publishing an ASCII version, most network management 1244 systems cannot import the YANG module directly from the PDF. Thus, 1245 not publishing an ASCII version of the YANG module would negatively 1246 impact implementers and deployers of YANG modules and would make 1247 potential IETF reviews of YANG modules more difficult. 1249 This appendix recommends that the IEEE 1588 WG consider future 1250 plans for: 1252 o Public availability of the ASCII YANG modules during project 1253 development. These ASCII files allow IETF participants to access 1254 these documents for pre-standard review purposes. 1256 o Public availability of the YANG portion of published IEEE 1588 1257 standards, provided as an ASCII file for each YANG module. 1258 These ASCII files are intended for use of the published IEEE 1259 1588 standard. 1261 As an example of public availability during project development, 1262 IEEE 802 uses the same repository that IETF uses for YANG module 1263 development (see https://github.com/YangModels/yang). IEEE branches 1264 are provided for experimental work (i.e. pre-PAR) as well as 1265 standard work (post-PAR drafts). IEEE-SA has approved use of this 1266 repository for project development, but not for published standards. 1268 As an example of public availability of YANG modules for published 1269 standards, IEEE 802.1 provides a public list of ASCII files for MIB 1270 (see http://www.ieee802.org/1/files/public/MIBs/ and 1271 http://www.ieee802.org/1/pages/MIBS.html), and analogous lists are 1272 planned for IEEE 802.1 YANG files. 1274 Authors' Addresses 1276 Yuanlong Jiang (Editor) 1277 Huawei Technologies Co., Ltd. 1278 Bantian, Longgang district 1279 Shenzhen 518129, China 1280 Email: jiangyuanlong@huawei.com 1282 Xian Liu 1283 Independent 1284 Shenzhen 518129, China 1285 lene.liuxian@foxmail.com 1287 Jinchun Xu 1288 Huawei Technologies Co., Ltd. 1289 Bantian, Longgang district 1290 Shenzhen 518129, China 1291 xujinchun@huawei.com 1293 Rodney Cummings (Editor) 1294 National Instruments 1295 11500 N. Mopac Expwy 1296 Bldg. C 1297 Austin, TX 78759-3504 1298 Email: Rodney.Cummings@ni.com