idnits 2.17.1 draft-ietf-tictoc-1588v2-yang-11.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 (January 3, 2019) is 1939 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: July 2019 January 3, 2019 11 YANG Data Model for IEEE 1588-2008 12 draft-ietf-tictoc-1588v2-yang-11 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 July 3, 2019. 46 Copyright Notice 48 Copyright (c) 2019 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 can be revised and extended to support these new 150 features. Moreover, the YANG "revision" MUST 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 may 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 SHOULD choose to return a warning upon 353 writing to a read-only member, or use the deviation mechanism to 354 develop a new deviation model as described in Section 7.20.3 of 355 [RFC7950]. 357 3. IEEE 1588-2008 YANG Module 359 This module imports typedef "interface-ref" from [RFC8343]. Most 360 attributes are based on the information model defined in [IEEE1588], 361 but their names are adapted to the YANG style of naming. 363 file "ietf-ptp@2018-09-10.yang" 364 //Note to RFC Editor: update the date to date of publication 365 module ietf-ptp { 366 yang-version 1.1; 367 namespace "urn:ietf:params:xml:ns:yang:ietf-ptp"; 368 prefix "ptp"; 370 import ietf-interfaces { 371 prefix if; 372 reference 373 "RFC8343: A YANG Data Model for Interface Management"; 374 } 376 organization "IETF TICTOC Working Group"; 377 contact 378 "WG Web: http://tools.ietf.org/wg/tictoc/ 379 WG List: 380 Editor: Yuanlong Jiang 381 382 Editor: Rodney Cummings 383 "; 384 description 385 "This YANG module defines a data model for the configuration 386 of IEEE 1588-2008 clocks, and also for retrieval of the state 387 data of IEEE 1588-2008 clocks."; 389 revision "2018-09-10" { 390 //Note to RFC Editor: update the date to date of publication 391 description "Initial version"; 392 reference "RFC XXXX: YANG Data Model for IEEE 1588-2008"; 393 //Note to RFC Editor: update RFC XXXX to the actual RFC number 395 } 397 typedef delay-mechanism-enumeration { 398 type enumeration { 399 enum e2e { 400 value 1; 401 description 402 "The port uses the delay request-response mechanism."; 403 } 404 enum p2p { 405 value 2; 406 description 407 "The port uses the peer delay mechanism."; 408 } 409 enum disabled { 410 value 254; 411 description 412 "The port does not implement any delay mechanism."; 413 } 414 } 415 description 416 "The propagation delay measuring option used by the 417 port. Values for this enumeration are specified 418 by the IEEE 1588 standard exclusively."; 419 reference 420 "IEEE Std 1588-2008: 8.2.5.4.4"; 421 } 423 typedef port-state-enumeration { 424 type enumeration { 425 enum initializing { 426 value 1; 427 description 428 "The port is initializing its data sets, hardware, and 429 communication facilities."; 430 } 431 enum faulty { 432 value 2; 433 description 434 "The port is in the fault state."; 435 } 436 enum disabled { 437 value 3; 438 description 439 "The port is disabled, and is not communicating PTP 440 messages (other than possibly PTP management 441 messages)."; 442 } 443 enum listening { 444 value 4; 445 description 446 "The port is listening for an Announce message."; 447 } 448 enum pre-master { 449 value 5; 450 description 451 "The port is in the pre-master state."; 452 } 453 enum master { 454 value 6; 455 description 456 "The port is behaving as a master port."; 457 } 458 enum passive { 459 value 7; 460 description 461 "The port is in the passive state."; 462 } 463 enum uncalibrated { 464 value 8; 465 description 466 "A master port has been selected, but the port is still 467 in the uncalibrated state."; 468 } 469 enum slave { 470 value 9; 471 description 472 "The port is synchronizing to the selected master port."; 473 } 474 } 476 description 477 "The current state of the protocol engine associated 478 with the port. Values for this enumeration are specified 479 by the IEEE 1588 standard exclusively."; 480 reference 481 "IEEE Std 1588-2008: 8.2.5.3.1, 9.2.5"; 482 } 484 typedef time-interval-type { 485 type int64; 486 description 487 "Derived data type for time interval, represented in units of 488 nanoseconds and multiplied by 2^16"; 489 reference 490 "IEEE Std 1588-2008: 5.3.2"; 491 } 493 typedef clock-identity-type { 494 type binary { 495 length "8"; 496 } 497 description 498 "Derived data type to identify a clock"; 499 reference 500 "IEEE Std 1588-2008: 5.3.4"; 501 } 503 grouping clock-quality-grouping { 504 description 505 "Derived data type for quality of a clock, which contains 506 clockClass, clockAccuracy and offsetScaledLogVariance."; 507 reference 508 "IEEE Std 1588-2008: 5.3.7"; 510 leaf clock-class { 511 type uint8; 512 default 248; 513 description 514 "The clockClass denotes the traceability of the time 515 or frequency distributed by the clock."; 516 } 518 leaf clock-accuracy { 519 type uint8; 520 description 521 "The clockAccuracy indicates the expected accuracy 522 of the clock."; 523 } 525 leaf offset-scaled-log-variance { 526 type uint16; 527 description 528 "The offsetScaledLogVariance provides an estimate of 529 the variations of the clock from a linear timescale 530 when it is not synchronized to another clock 531 using the protocol."; 532 } 533 } 535 container ptp { 536 description 537 "The PTP struct containing all attributes of PTP data set, 538 other optional PTP attributes can be augmented as well."; 540 list instance-list { 542 key "instance-number"; 543 description 544 "List of one or more PTP data sets in the device (see IEEE 545 Std 1588-2008 subclause 6.3). 546 Each PTP data set 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 uint32; 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). This data set represents 563 the configuration/state required for operation 564 of Precision Time Protocol (PTP) state machines."; 566 leaf two-step-flag { 567 type boolean; 568 description 569 "When set to true, the clock is a two-step clock; 570 otherwise,the clock is a one-step clock."; 571 } 573 leaf clock-identity { 574 type clock-identity-type; 575 config false; 576 description 577 "The clockIdentity of the local clock"; 578 } 580 leaf number-ports { 581 type uint16; 582 description 583 "The number of PTP ports on the instance."; 584 } 586 container clock-quality { 587 description 588 "The clockQuality of the local clock."; 590 uses clock-quality-grouping; 591 } 593 leaf priority1 { 594 type uint8; 595 description 596 "The priority1 attribute of the local clock."; 597 } 599 leaf priority2{ 600 type uint8; 601 description 602 "The priority2 attribute of the local clock."; 603 } 605 leaf domain-number { 606 type uint8; 607 description 608 "The domain number of the current syntonization 609 domain."; 610 } 612 leaf slave-only { 613 type boolean; 614 description 615 "When set to true, the clock is a slave-only clock."; 616 } 618 } 620 container current-ds { 621 description 622 "The current data set of the clock (see IEEE Std 623 1588-2008 subclause 8.2.2). This data set represents 624 local states learned from the exchange of 625 Precision Time Protocol (PTP) messages."; 627 leaf steps-removed { 628 type uint16; 629 default 0; 630 description 631 "The number of communication paths traversed 632 between the local clock and the grandmaster clock."; 633 } 635 leaf offset-from-master { 636 type time-interval-type; 637 description 638 "The current value of the time difference between 639 a master and a slave clock as computed by the slave."; 640 } 642 leaf mean-path-delay { 643 type time-interval-type; 644 description 645 "The current value of the mean propagation time between 646 a master and a slave clock as computed by the slave."; 648 } 650 } 652 container parent-ds { 653 description 654 "The parent data set of the clock (see IEEE Std 1588-2008 655 subclause 8.2.3)."; 657 container parent-port-identity { 658 description 659 "The portIdentity of the port on the master, it 660 contains two members: clockIdentity and portNumber."; 661 reference 662 "IEEE Std 1588-2008: 5.3.5"; 664 leaf clock-identity { 665 type clock-identity-type; 666 description 667 "Identity of the clock"; 668 } 670 leaf port-number { 671 type uint16; 672 description 673 "Port number"; 674 } 675 } 677 leaf parent-stats { 678 type boolean; 679 default false; 680 description 681 "When set to true, the values of 682 observedParentOffsetScaledLogVariance and 683 observedParentClockPhaseChangeRate of parentDS 684 have been measured and are valid."; 685 } 687 leaf observed-parent-offset-scaled-log-variance { 688 type uint16; 689 default 65535; 690 description 691 "An estimate of the parent clock's PTP variance 692 as observed by the slave clock."; 693 } 695 leaf observed-parent-clock-phase-change-rate { 696 type int32; 697 description 698 "An estimate of the parent clock's phase change rate 699 as observed by the slave clock."; 700 } 702 leaf grandmaster-identity { 703 type clock-identity-type; 704 description 705 "The clockIdentity attribute of the grandmaster clock."; 706 } 708 container grandmaster-clock-quality { 709 description 710 "The clockQuality of the grandmaster clock."; 711 uses clock-quality-grouping; 712 } 714 leaf grandmaster-priority1 { 715 type uint8; 716 description 717 "The priority1 attribute of the grandmaster clock."; 718 } 720 leaf grandmaster-priority2 { 721 type uint8; 722 description 723 "The priority2 attribute of the grandmaster clock."; 724 } 726 } 728 container time-properties-ds { 729 description 730 "The timeProperties data set of the clock (see 731 IEEE Std 1588-2008 subclause 8.2.4)."; 733 leaf current-utc-offset-valid { 734 type boolean; 735 description 736 "When set to true, the current UTC offset is valid."; 737 } 738 leaf current-utc-offset { 739 when "../current-utc-offset-valid='true'"; 740 type int16; 741 description 742 "The offset between TAI and UTC when the epoch of the 743 PTP system is the PTP epoch in units of seconds, i.e., 744 when ptp-timescale is TRUE; otherwise, the value has 745 no meaning."; 746 } 748 leaf leap59 { 749 type boolean; 750 description 751 "When set to true, the last minute of the current UTC 752 day contains 59 seconds."; 753 } 755 leaf leap61 { 756 type boolean; 757 description 758 "When set to true, the last minute of the current UTC 759 day contains 61 seconds."; 760 } 762 leaf time-traceable { 763 type boolean; 764 description 765 "When set to true, the timescale and the 766 currentUtcOffset are traceable to a primary 767 reference."; 768 } 770 leaf frequency-traceable { 771 type boolean; 772 description 773 "When set to true, the frequency determining the 774 timescale is traceable to a primary reference."; 775 } 776 leaf ptp-timescale { 777 type boolean; 778 description 779 "When set to true, the clock timescale of the 780 grandmaster clock is PTP; otherwise, the timescale is 781 ARB 782 (arbitrary)."; 783 } 785 leaf time-source { 786 type uint8; 787 description 788 "The source of time used by the grandmaster clock."; 789 } 790 } 792 list port-ds-list { 793 key "port-number"; 794 description 795 "List of port data sets of the clock (see IEEE Std 796 1588-2008 subclause 8.2.5)."; 798 leaf port-number { 799 type uint16; 801 description 802 "Port number. 803 The data sets (i.e., information model) of IEEE Std 804 1588-2008 specify a member portDS.portIdentity, which 805 uses a typed struct with members clockIdentity and 806 portNumber. 808 In this YANG data model, portIdentity is not modeled 809 in the port-ds-list, however, its members are provided 810 as follows: 811 portIdentity.portNumber is provided as this port- 812 number leaf in port-ds-list; and 813 portIdentity.clockIdentity is provided as the clock- 814 identity leaf in default-ds of the instance 815 (i.e., ../../default-ds/clock-identity)."; 816 } 818 leaf port-state { 819 type port-state-enumeration; 820 default "initializing"; 821 description 822 "Current state associated with the port."; 824 } 826 leaf underlying-interface { 827 type if:interface-ref; 828 description 829 "Reference to the configured underlying interface that 830 is used by this PTP Port (see RFC 8343)."; 831 } 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 config false; 909 description 910 "The clockIdentity of the transparent clock."; 911 } 913 leaf number-ports { 914 type uint16; 915 description 916 "The number of PTP ports on the transparent clock."; 917 } 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 (see 930 IEEE Std 1588-2008 subclause 10.1)."; 931 } 932 } 934 list transparent-clock-port-ds-list { 935 key "port-number"; 936 description 937 "List of transparentClockPort data sets of the transparent 938 clock (see IEEE Std 1588-2008 subclause 8.3.3)."; 940 leaf port-number { 941 type uint16; 942 description 943 "Port number. 944 The data sets (i.e., information model) of IEEE Std 945 1588-2008 specify a member 946 transparentClockPortDS.portIdentity, which uses a typed 947 struct with members clockIdentity and portNumber. 949 In this YANG data model, portIdentity is not modeled in 950 the transparent-clock-port-ds-list, however, its 951 members are provided as follows: 952 portIdentity.portNumber is provided as this leaf member 953 in transparent-clock-port-ds-list; and 954 portIdentity.clockIdentity is provided as the clock- 955 identity leaf in transparent-clock-default-ds 956 (i.e., ../../transparent-clock-default-ds/clock- 957 identity)."; 959 } 961 leaf log-min-pdelay-req-interval { 962 type int8; 963 description 964 "The logarithm to the base 2 of the 965 minPdelayReqInterval (minimum permitted mean time 966 interval between successive Pdelay_Req messages)."; 967 } 969 leaf faulty-flag { 970 type boolean; 971 default false; 972 description 973 "When set to true, the port is faulty."; 974 } 976 leaf peer-mean-path-delay { 977 type time-interval-type; 978 default 0; 979 description 980 "An estimate of the current one-way propagation delay 981 on the link when the delayMechanism is P2P; otherwise, 982 it is zero."; 983 } 985 } 986 } 987 } 989 991 4. Security Considerations 993 The YANG module specified in this document defines a schema for 994 data that is designed to be accessed via network management 995 protocols such as NETCONF [RFC6241] or RESTCONF [RFC8040]. The 996 lowest NETCONF layer is the secure transport layer, and the 997 mandatory-to-implement secure transport is Secure Shell (SSH) 998 [RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory- 999 to-implement secure transport is TLS [RFC8446]. Furthermore, 1000 general security considerations of time protocols are discussed in 1001 [RFC7384]. 1003 The NETCONF access control model [RFC8341] provides the means to 1004 restrict access for particular NETCONF or RESTCONF users to a 1005 preconfigured subset of all available NETCONF or RESTCONF protocol 1006 operations and content. 1008 There are a number of data nodes defined in this YANG module are 1009 writable, and the involved subtrees that are sensitive include: 1011 /ptp/instance-list specifies an instance (i.e., PTP data sets) for 1012 an OC or BC. 1014 /ptp/transparent-clock-default-ds specifies a default data set for 1015 a TC. 1017 /ptp/transparent-clock-port-ds-list specifies a list of port data 1018 sets for a TC. 1020 Write operations (e.g., edit-config) to these data nodes without 1021 proper protection can have a negative effect on network operations. 1022 Specifically, an inappropriate configuration of them may adversely 1023 impact a PTP synchronization network. For example, loss of 1024 synchronization on a clock, accuracy degradation on a set of clocks, 1025 or even break down of a whole synchronization network. 1027 5. IANA Considerations 1029 This document registers the following URI in the "IETF XML 1030 registry" [RFC3688]: 1031 URI: urn:ietf:params:xml:ns:yang:ietf-ptp 1032 Registrant Contact: The IESG 1033 XML: N/A; the requested URI is an XML namespace 1035 This document registers the following YANG module in the "YANG 1036 Module Names" registry [RFC6020]: 1037 Name: ietf-ptp 1038 Namespace: urn:ietf:params:xml:ns:yang:ietf-ptp 1039 Prefix: ptp 1040 Reference: RFC XXXX 1042 6. References 1044 6.1. Normative References 1046 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1047 Requirement Levels", BCP 14, RFC 2119, March 1997 1049 [RFC3688] Mealling, M., "The IETF XML Registry", RFC 3688, 1050 January 2004 1052 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 1053 Network Configuration Protocol (NETCONF) ", RFC 6020, 1054 October 2010 1056 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and Bierman, 1057 A., "Network Configuration Protocol (NETCONF)", RFC 6241, 1058 June 2011 1060 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 1061 Shell (SSH)", RFC 6242, June 2011 1063 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 1064 July 2013 1066 [RFC7950] Bjorklund, M., "The YANG 1.1 Data Modeling Language", RFC 1067 7950, August 2016 1069 [RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF 1070 Protocol", RFC 8040, January 2017 1072 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 1073 2119 Key Words", BCP 14, RFC 8174, May 2017 1075 [RFC8341] Bierman, A. and Bjorklund, M., "Network Configuration 1076 Protocol (NETCONF) Access Control Model", RFC 8341, March 1077 2018 1079 [RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K., 1080 and R. Wilton, "Network Management Datastore Architecture 1081 (NMDA)", RFC 8342, March 2018 1083 [RFC8343] Bjorklund, M., "A YANG Data Model for Interface 1084 Management", RFC 8343, March 2018 1086 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) 1087 Protocol Version 1.3", RFC 8446, August 2018 1089 [IEEE1588] IEEE, "IEEE Standard for a Precision Clock 1090 Synchronization Protocol for Networked Measurement and 1091 Control Systems", IEEE Std 1588-2008, July 2008 1093 6.2. Informative References 1095 [IEEE8021AS] IEEE, "Timing and Synchronizations for Time-Sensitive 1096 Applications in Bridged Local Area Networks", IEEE 1097 802.1AS-2001, 2011 1099 [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between 1100 Information Models and Data Models", RFC 3444, January 1101 2003 1103 [RFC4663] Harrington, D., "Transferring MIB Work from IETF Bridge 1104 MIB WG to IEEE 802.1 WG", RFC 4663, September 2006 1106 [RFC7384] Mizrahi, T., "Security Requirements of Time Protocols in 1107 Packet Switched Networks", RFC 7384, October 2014 1109 [RFC8340] Bjorklund, M., and Berger, L., "YANG Tree Diagrams", RFC 1110 8340, March 2018 1112 [RFC8173] Shankarkumar, V., Montini, L., Frost, T., and Dowd, G., 1113 "Precision Time Protocol Version 2 (PTPv2) Management 1114 Information Base", RFC 8173, June 2017 1116 7. Acknowledgments 1118 The authors would like to thank Tom Petch, Radek Krejci, Mahesh 1119 Jethanandani, Tal Mizrahi, Opher Ronen, Liang Geng, Alex Campbell, 1120 Joe Gwinn, John Fletcher, William Zhao and Dave Thaler for their 1121 valuable reviews and suggestions, thank Benoit Claise and Radek 1122 Krejci for their validation of the YANG module, and thank Jingfei 1123 Lv and Zitao Wang for their discussions on IEEE 1588 and YANG 1124 respectively. 1126 Appendix A Transferring YANG Work to IEEE 1588 WG 1128 This Appendix is informational. 1130 This appendix describes a future plan to transition responsibility 1131 for IEEE 1588 YANG modules from the IETF TICTOC Working Group (WG) 1132 to the IEEE 1588 WG, which develops the time synchronization 1133 technology that the YANG modules are designed to manage. 1135 This appendix is forward-looking with regard to future 1136 standardization roadmaps in IETF and IEEE. Since those roadmaps 1137 cannot be predicted with significant accuracy, this appendix is 1138 informational, and it does not specify imperatives or normative 1139 specifications of any kind. 1141 The IEEE 1588-2008 YANG module of this standard represents a 1142 cooperation between IETF (for YANG) and IEEE (for 1588). For the 1143 initial standardization of IEEE-1588 YANG modules, the information 1144 model is relatively clear (i.e., IEEE 1588 data sets), but 1145 expertise in YANG is required, making IETF an appropriate location 1146 for the standards. The TICTOC WG has expertise with IEEE 1588, 1147 making it the appropriate location within IETF. 1149 The IEEE 1588 WG anticipates future changes to its standard on an 1150 ongoing basis. As IEEE 1588 WG members gain practical expertise 1151 with YANG, the IEEE 1588 WG will become more appropriate for 1152 standardization of its YANG modules. As the IEEE 1588 standard is 1153 revised and/or amended, IEEE 1588 members can more effectively 1154 synchronize the revision of this YANG module with future versions 1155 of the IEEE 1588 standard. 1157 This appendix is meant to establish some clear expectations between 1158 IETF and IEEE about the future transfer of IEEE 1588 YANG modules 1159 to the IEEE 1588 WG. The goal is to assist in making the future 1160 transfer as smooth as possible. As the transfer takes place, some 1161 case-by-case situations are likely to arise, which can be handled 1162 by discussion on the IETF TICTOC WG mailing lists and/or 1163 appropriate liaisons. 1165 This appendix obtained insight from [RFC4663], an informational 1166 memo that described a similar transfer of MIB work from the IETF 1167 Bridge MIB WG to the IEEE 802.1 WG. 1169 A.1. Assumptions for the Transfer 1171 For the purposes of discussion in this appendix, assume that the 1172 IESG has approved the publication of an RFC containing a YANG 1173 module for a published IEEE 1588 standard. As of this writing, 1174 this is IEEE Std 1588-2008, but it is possible that YANG modules 1175 for subsequent 1588 revisions could be published from the IETF 1176 TICTOC WG. For discussion in this appendix, we use the phrase 1177 "last IETF 1588 YANG" to refer to the most recently published 1588 1178 YANG module from the IETF TICTOC WG. 1180 The IEEE-SA Standards Board New Standards Committee (NesCom) 1181 handles new Project Authorization Requests (PARs) (see 1182 http://standards.ieee.org/board/nes/). PARs are roughly the 1183 equivalent of IETF Working Group Charters and include information 1184 concerning the scope, purpose, and justification for 1185 standardization projects. 1187 Assume that IEEE 1588 has an approved PAR that explicitly specifies 1188 development of a YANG module. The transfer of YANG work will occur 1189 in the context of this IEEE 1588 PAR. For discussion in this 1190 appendix, we use the phrase "first IEEE 1588 YANG" to refer to the 1191 first IEEE 1588 standard for YANG. 1193 Assume that as part of the transfer of YANG work, the IETF TICTOC 1194 WG agrees to cease all work on standard YANG modules for IEEE 1588. 1196 Assume that the IEEE 1588 WG has participated in the development of 1197 the last IETF 1588 YANG module, such that the first IEEE 1588 YANG 1198 module will effectively be a revision of it. In other words, the 1199 transfer of YANG work will be relatively clean. 1201 The actual conditions for the future transfer can be such that the 1202 preceding assumptions do not hold. Exceptions to the assumptions 1203 will need to be addressed on a case-by-case basis at the time of 1204 the transfer. This appendix describes topics that can be addressed 1205 based on the preceding assumptions. 1207 A.2. Intellectual Property Considerations 1209 During review of the legal issues associated with transferring 1210 Bridge MIB WG documents to the IEEE 802.1 WG (Section 3.1 and 1211 Section 9 of [RFC4663]), it was concluded that the IETF does not 1212 have sufficient legal authority to make the transfer to IEEE 1213 without the consent of the document authors. 1215 If the last IETF 1588 YANG is published as a RFC, the work is 1216 required to be transferred from the IETF to the IEEE, so that IEEE 1217 1588 WG can begin working on the first IEEE 1588 YANG. 1219 When work on the first IEEE YANG module begins in the IEEE 1588 WG, 1220 that work derives from the last IETF YANG module of this RFC, 1221 requiring a transfer of that work from the IETF to the IEEE. In 1222 order to avoid having the transfer of that work be dependent on the 1223 availability of this RFC's authors at the time of its publication, 1224 the IEEE Standards Association department of Risk Management and 1225 Licensing provided the appropriate forms and mechanisms for this 1226 document's authors to assign a non-exclusive license for IEEE to 1227 create derivative works from this document. Those IEEE forms and 1228 mechanisms will be updated as needed for any future IETF YANG 1229 modules for IEEE 1588 (The signed forms are held by the IEEE 1230 Standards Association department of Risk Management and Licensing.). 1231 This will help to make the future transfer of work from IETF to 1232 IEEE occur as smoothly as possible. 1234 As stated in the initial "Status of this Memo", the YANG module in 1235 this document conforms to the provisions of BCP 78. The IETF will 1236 retain all the rights granted at the time of publication in the 1237 published RFCs. 1239 A.3. Namespace and Module Name 1241 As specified in Section 5 "IANA Considerations", the YANG module in 1242 this document uses IETF as the root of its URN namespace and YANG 1243 module name. 1245 Use of IETF as the root of these names implies that the YANG module 1246 is standardized in a Working Group of IETF, using the IETF 1247 processes. If the IEEE 1588 Working Group were to continue using 1248 these names rooted in IETF, the IEEE 1588 YANG standardization 1249 would need to continue in the IETF. The goal of transferring the 1250 YANG work is to avoid this sort of dependency between standards 1251 organizations. 1253 IEEE 802 has an active PAR (IEEE P802d) for creating a URN 1254 namespace for IEEE use (see 1255 http://standards.ieee.org/develop/project/802d.html). It is likely 1256 that this IEEE 802 PAR will be approved and published prior to the 1257 transfer of YANG work to the IEEE 1588 WG. If so, the IEEE 1588 WG 1258 can use the IEEE URN namespace for the first IEEE 1588 YANG module, 1259 such as: 1261 urn:ieee:Std:1588:yang:ieee1588-ptp 1263 where "ieee1588-ptp" is the registered YANG module name in the IEEE. 1265 Under the assumptions of section A.1, the first IEEE 1588 YANG 1266 module's prefix will be the same as the last IETF 1588 YANG 1267 module's prefix (i.e. "ptp"). Consequently, other YANG modules can 1268 preserve the same import prefix "ptp" to access PTP nodes during 1269 the migration from the last IETF 1588 YANG module to the first IEEE 1270 1588 YANG module. 1272 The result of these name changes are that for complete 1273 compatibility, a server (i.e., IEEE 1588 node) can choose to 1274 implement a YANG module for the last IETF 1588 YANG module (with 1275 IETF root) as well as the first IEEE 1588 YANG module (with IEEE 1276 root). Since the content of the YANG module transferred are the 1277 same, the server implementation is effectively common for both. 1279 From a client's perspective, a client of the last IETF 1588 YANG 1280 module (or earlier) looks for the IETF-rooted module name; and a 1281 client of the first IEEE 1588 YANG module (or later) looks for the 1282 IEEE-rooted module name. 1284 A.4. IEEE 1588 YANG Modules in ASCII Format 1286 Although IEEE 1588 can certainly decide to publish YANG modules 1287 only in the PDF format that they use for their standard documents, 1288 without publishing an ASCII version, most network management 1289 systems cannot import the YANG module directly from the PDF. Thus, 1290 not publishing an ASCII version of the YANG module would negatively 1291 impact implementers and deployers of YANG modules and would make 1292 potential IETF reviews of YANG modules more difficult. 1294 This appendix recommends that the IEEE 1588 WG consider future 1295 plans for: 1297 o Public availability of the ASCII YANG modules during project 1298 development. These ASCII files allow IETF participants to access 1299 these documents for pre-standard review purposes. 1301 o Public availability of the YANG portion of published IEEE 1588 1302 standards, provided as an ASCII file for each YANG module. 1303 These ASCII files are intended for use of the published IEEE 1304 1588 standard. 1306 As an example of public availability during project development, 1307 IEEE 802 uses the same repository that IETF uses for YANG module 1308 development (see https://github.com/YangModels/yang). IEEE branches 1309 are provided for experimental work (i.e. pre-PAR) as well as 1310 standard work (post-PAR drafts). IEEE-SA has approved use of this 1311 repository for project development, but not for published standards. 1313 As an example of public availability of YANG modules for published 1314 standards, IEEE 802.1 provides a public list of ASCII files for MIB 1315 (see http://www.ieee802.org/1/files/public/MIBs/ and 1316 http://www.ieee802.org/1/pages/MIBS.html), and analogous lists are 1317 planned for IEEE 802.1 YANG files. 1319 Authors' Addresses 1321 Yuanlong Jiang (Editor) 1322 Huawei Technologies Co., Ltd. 1323 Bantian, Longgang district 1324 Shenzhen 518129, China 1325 Email: jiangyuanlong@huawei.com 1327 Xian Liu 1328 Independent 1329 Shenzhen 518129, China 1330 lene.liuxian@foxmail.com 1332 Jinchun Xu 1333 Huawei Technologies Co., Ltd. 1334 Bantian, Longgang district 1335 Shenzhen 518129, China 1336 xujinchun@huawei.com 1338 Rodney Cummings (Editor) 1339 National Instruments 1340 11500 N. Mopac Expwy 1341 Bldg. C 1342 Austin, TX 78759-3504 1343 Email: Rodney.Cummings@ni.com