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