idnits 2.17.1 draft-ietf-tictoc-1588v2-yang-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (October 20, 2016) is 2717 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' == Outdated reference: A later version (-12) exists of draft-ietf-tictoc-ptp-mib-11 == Outdated reference: A later version (-18) exists of draft-ietf-netconf-restconf-17 -- Obsolete informational reference (is this intentional?): RFC 6536 (Obsoleted by RFC 8341) Summary: 0 errors (**), 0 flaws (~~), 4 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: April 2017 October 20, 2016 9 YANG Data Model for IEEE 1588v2 10 draft-ietf-tictoc-1588v2-yang-00 12 Status of this Memo 14 This Internet-Draft is submitted to IETF in full conformance with 15 the provisions of BCP 78 and BCP 79. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six 23 months and may be updated, replaced, or obsoleted by other 24 documents at any time. It is inappropriate to use Internet-Drafts 25 as reference material or to cite them other than as "work in 26 progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html 34 This Internet-Draft will expire on April 20, 2017. 36 Copyright Notice 38 Copyright (c) 2016 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with 46 respect to this document. Code Components extracted from this 47 document must include Simplified BSD License text as described in 48 Section 4.e of the Trust Legal Provisions and are provided without 49 warranty as described in the Simplified BSD License. 51 Abstract 53 This document defines a YANG data model for the configuration of 54 IEEE 1588-2008 devices and clocks, and also retrieval of the 55 configuration information, data set and running states of IEEE 56 1588-2008 clocks. 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 ........... 7 65 3. IEEE 1588-2008 YANG Module ................................ 8 66 4. Security Considerations .................................. 20 67 5. IANA Considerations ...................................... 20 68 6. References ............................................... 21 69 6.1. Normative References .................................. 21 70 6.2. Informative References ................................ 21 71 7. Acknowledgments .......................................... 22 72 Appendix A Transferring YANG Work to IEEE 1588 WG (Informational) 73 ............................................................... 22 74 A.1. Assumptions for the Transfer .......................... 23 75 A.2. Intellectual Property Considerations .................. 24 76 A.3. Namespace and Module Name ............................. 24 77 A.4. IEEE 1588 YANG Modules in ASCII Format ................ 25 79 1. Introduction 81 As a synchronization protocol, IEEE 1588-2008 (also known as IEEE 82 1588v2) [IEEE1588] is widely supported in the carrier networks, 83 industrial networks, automotive networks, and many other 84 applications. It can provide high precision time synchronization as 85 high as nano-seconds. The protocol depends on a Precision Time 86 Protocol (PTP) engine to decide its state automatically, and a PTP 87 transportation layer to carry the PTP timing and various quality 88 messages. The configuration parameters and state data sets of IEEE 89 1588-2008 are numerous. 91 According to the concepts described in [RFC3444], IEEE 1588-2008 92 itself provides an information model in its normative 93 specifications for the data sets (in IEEE 1588-2008 clause 8). Some 94 standardization organizations including the IETF have specified 95 data models in MIBs (Management Information Bases) for IEEE 1588- 96 2008 data sets (e.g. [PTP-MIB], [IEEE8021AS]). Since these MIBs are 97 typically focused on retrieval of state data using the Simple 98 Network Management Protocol (SNMP), configuration is not considered. 100 Some service providers and applications require that the management 101 of the IEEE 1588-2008 synchronization network be flexible and more 102 Internet-based (typically overlaid on their transport networks). 103 Software Defined Network (SDN) is another driving factor which 104 demands an improved configuration capability of synchronization 105 networks. 107 YANG [RFC6020] is a data modeling language used to model 108 configuration and state data manipulated by network management 109 protocols like the Network Configuration Protocol (NETCONF) 110 [RFC6241]. A small set of built-in data types are defined in 111 [RFC6020], and a collection of common data types are further 112 defined in [RFC6991]. Advantages of YANG include Internet based 113 configuration capability, validation, roll-back and so on. All of 114 these characteristics make it attractive to become another 115 candidate modeling language for IEEE 1588-2008. 117 This document defines a YANG [RFC6020] data model for the 118 configuration of IEEE 1588-2008 devices and clocks, and also 119 retrieval of the state data of IEEE 1588-2008 clocks. The data 120 model is based on the PTP data sets as specified in [IEEE1588]. The 121 router specific IEEE 1588-2008 information is out of scope of this 122 document. 124 When used in practice, network products in support of 125 synchronization typically conform to one or more IEEE 1588-2008 126 profiles. Each profile specifies how IEEE 1588-2008 is used in a 127 given industry (e.g. telecom, automotive) and application. A 128 profile can require features that are optional in IEEE 1588-2008, 129 and it can specify new features that use IEEE 1588-2008 as a 130 foundation. 132 It is expected that the IEEE 1588-2008 YANG module will be used as 133 follows: 135 o The IEEE 1588-2008 YANG module can be used as-is for products 136 that conform to one of the default profiles specified in IEEE 1588- 137 2008. 139 o When the IEEE 1588 standard is revised (e.g. the IEEE 1588 140 revision in progress scheduled to be published in 2017), it will 141 add some new optional features to its data sets. The YANG module 142 of this document can be revised and extended to add the new 143 features (e.g. of IEEE 1588-2017). The YANG "revision" can be used 144 to indicate changes to the YANG module. 146 o A profile standard based on IEEE 1588-2008 may create a 147 dedicated YANG module for its profile. The profile's YANG module 148 may use YANG "import" to import the IEEE 1588-2008 YANG module as 149 its foundation. Then the profile's YANG module can use YANG 150 "augment" to add any profile-specific enhancements. 152 o A product that conforms to a profile standard can also create 153 its own YANG module. The product's YANG module can "import" the 154 profile's module, and then use YANG "augment" to add any product- 155 specific enhancements. 157 1.1. Conventions used in this document 159 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 160 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 161 this document are to be interpreted as described in [RFC2119]. 163 1.2. Terminology 165 Terminologies used in this document are extracted from [IEEE1588] 166 and [PTP-MIB]. 168 BC Boundary Clock 170 DS Data Set 172 E2E End-to-End 174 EUI Extended Unique Identifier. 176 GPS Global Positioning System 178 IANA Internet Assigned Numbers Authority 180 IP Internet Protocol 182 NIST National Institute of Standards and Technology 184 NTP Network Time Protocol 185 OC Ordinary Clock 187 P2P Peer-to-Peer 189 PTP Precision Time Protocol 191 TAI International Atomic Time 193 TC Transparent Clock 195 UTC Coordinated Universal Time 197 2. IEEE 1588-2008 YANG Model hierarchy 199 This section describes the hierarchy of IEEE 1588-2008 YANG module. 200 Query and configuration of device wide or port specific 201 configuration information and clock data set is described for this 202 version. 204 Query and configuration of clock information include: 206 - Clock data set attributes in a clock node, including: current-ds, 207 parent-ds, default-ds, time-properties-ds, and transparentClock- 208 default-ds. 210 - Port specific data set attributes, including: port-ds and 211 transparentClock-port-ds. 213 A simplified graphical representation of the data model is 214 typically used by YANG modules as described in [REST-CONF]. This 215 document uses the same representation and the meaning of the 216 symbols in these diagrams is as follows: 218 o Brackets "[" and "]" enclose list keys. 220 o Abbreviations before data node names: "rw" means configuration 221 data (read-write) and "ro" state data (read-only). 223 o Symbols after data node names: "?" means an optional node, "!" 224 means a presence container, and "*" denotes a list and leaf-list. 226 o Parentheses enclose choice and case nodes, and case nodes are 227 also marked with a colon (":"). 229 o Ellipsis ("...") stands for contents of subtrees that are not 230 shown. 232 module: ietf-ptp-dataset 233 +--rw instance-list* [instance-number] 234 | +--rw instance-number uint8 235 | +--rw default-ds 236 | | +--rw two-step-flag? boolean 237 | | +--rw clock-identity? binary 238 | | +--rw number-ports? uint16 239 | | +--rw clock-quality 240 | | | +--rw clock-class? uint8 241 | | | +--rw clock-accuracy? uint8 242 | | | +--rw offset-scaled-log-variance? uint16 243 | | +--rw priority1? uint8 244 | | +--rw priority2? uint8 245 | | +--rw domain-number uint8 246 | | +--rw slave-only? boolean 247 | +--rw current-ds 248 | | +--rw steps-removed? uint16 249 | | +--rw offset-from-master? binary 250 | | +--rw mean-path-delay? binary 251 | +--rw parent-ds 252 | | +--rw parent-port-identity 253 | | | +--rw clock-identity? binary 254 | | | +--rw port-number? uint16 255 | | +--rw parent-stats? boolean 256 | | +--rw observed-parent-offset-scaled-log-variance? uint16 257 | | +--rw observed-parent-clock-phase-change-rate? int32 258 | | +--rw grandmaster-identity? binary 259 | | +--rw grandmaster-clock-quality 260 | | | +--rw grandmaster-clock-class? uint8 261 | | | +--rw grandmaster-clock-accuracy? uint8 262 | | | +--rw grandmaster-offset-scaled-log-variance? uint16 263 | | +--rw grandmaster-priority1? uint8 264 | | +--rw grandmaster-priority2? uint8 265 | +--rw time-properties-ds 266 | | +--rw current-utc-offset-valid? boolean 267 | | +--rw current-utc-offset? uint16 268 | | +--rw leap59? boolean 269 | | +--rw leap61? boolean 270 | | +--rw time-traceable? boolean 271 | | +--rw frequency-traceable? boolean 272 | | +--rw ptp-timescale? boolean 273 | | +--rw time-source? uint8 274 | +--rw port-ds-list* [port-number] 275 | +--rw port-number -> ../port-identity/port-number 276 | +--rw port-identity 277 | | +--rw clock-identity? binary 278 | | +--rw port-number? uint16 279 | +--rw port-state? uint8 280 | +--rw log-min-delay-req-interval? int8 281 | +--rw peer-mean-path-delay? int64 282 | +--rw log-announce-interval? int8 283 | +--rw announce-receipt-timeout? uint8 284 | +--rw log-sync-interval? int8 285 | +--rw delay-mechanism? enumeration 286 | +--rw log-min-pdelay-req-interval? int8 287 | +--rw version-number? uint8 288 +--rw transparent-clock-default-ds 289 | +--rw clock-identity? binary 290 | +--rw number-ports? uint16 291 | +--rw delay-mechanism? enumeration 292 | +--rw primary-domain? uint8 293 +--rw transparent-clock-port-ds-list* [port-number] 294 +--rw port-number -> ../port-identity/port-number 295 +--rw port-identity 296 | +--rw clock-identity? binary 297 | +--rw port-number? uint16 298 +--rw log-min-pdelay-req-interval? int8 299 +--rw faulty-flag? boolean 300 +--rw peer-mean-path-delay? int64 302 2.1. Interpretations from IEEE 1588 Working Group 304 The preceding model and the associated YANG module have some subtle 305 differences from the data set specifications of IEEE Std 1588-2008. 306 These differences are based on interpretation from the IEEE 1588 307 Working Group, and are intended to provide compatibility with 308 future revisions of the IEEE 1588 standard. 310 In IEEE Std 1588-2008, a physical product can implement multiple 311 PTP clocks (i.e. ordinary, boundary, or transparent clock). As 312 specified in 1588-2008 subclause 7.1, each of the multiple clocks 313 operates in an independent domain. However, the organization of 314 multiple PTP domains was not clear in the data sets of IEEE Std 315 1588-2008. This document introduces the concept of PTP instance as 316 described in the new revision of IEEE 1588. The instance concept is 317 used exclusively to allow for optional support of multiple domains. 318 The instance number has no usage within PTP messages. 320 Based on statements in IEEE 1588-2008 subclauses 8.3.1. and 10.1, 321 most transparent clock products have interpreted the transparent 322 clock data sets to reside as a singleton at the root level of the 323 managed product. Since 1588-2008 transparent clocks are domain 324 independent, the instance concept is not applicable for them. 326 3. IEEE 1588-2008 YANG Module 328 file "ietf-ptp-dataset@2016-10-20" 330 module ietf-ptp-dataset{ 331 namespace "urn:ietf:params:xml:ns:yang:ietf-ptp-dataset"; 332 prefix "ptp-dataset"; 333 organization "IETF TICTOC WG"; 334 contact 335 "WG Web: http://tools.ietf.org/wg/tictoc/ 336 WG List: 337 WG Chair: Karen O'Donoghue 338 339 WG Chair: Yaakov Stein 340 341 Editor: Yuanlong Jiang 342 343 Editor: Rodney Cummings 344 "; 345 description 346 "This YANG module defines a data model for the configuration 347 of IEEE 1588-2008 clocks, and also retrieval of the state 348 data of IEEE 1588-2008 clocks."; 349 revision "2016-10-20" { 350 description "Original version."; 351 reference "draft-ietf-tictoc-1588v2-yang"; 352 } 354 grouping default-ds-entry { 355 description 356 "Collection of members of the default data set."; 358 leaf two-step-flag { 359 type boolean; 360 description 361 "The flag indicates whether the Two Step process is 362 used."; 363 } 364 leaf clock-identity { 365 type binary { 366 length "8"; 367 } 368 description 369 "The clockIdentity of the local clock"; 370 } 372 leaf number-ports { 373 type uint16; 374 description 375 "The number of PTP ports on the device."; 376 } 378 container clock-quality { 379 description 380 "The clockQuality of the local clock. It contains 381 clockClass, clockAccuracy and offsetScaledLogVariance."; 383 leaf clock-class { 384 type uint8; 385 default 248; 386 description 387 "The clockClass denotes the traceability of the time 388 or frequency distributed by the grandmaster clock."; 389 } 390 leaf clock-accuracy { 391 type uint8; 392 description 393 "The clockAccuracy indicates the expected accuracy 394 of a clock when it is the grandmaster."; 395 } 396 leaf offset-scaled-log-variance { 397 type uint16; 398 description 399 "An estimate of the variations of the local clock 400 from a linear timescale when it is not synchronized 401 to another clock using the protocol."; 402 } 403 } 405 leaf priority1 { 406 type uint8; 407 description 408 "The priority1 attribute of the local clock."; 409 } 410 leaf priority2{ 411 type uint8; 412 description 413 "The priority2 attribute of the local clock. "; 414 } 416 leaf domain-number { 417 type uint8; 418 description 419 "The domain number of the current syntonization 420 domain."; 421 } 423 leaf slave-only { 424 type boolean; 425 description 426 "Indicates whether the clock is a slave-only clock."; 428 } 429 } 431 grouping current-ds-entry { 432 description 433 "Collection of members of current data set."; 435 leaf steps-removed { 436 type uint16; 437 default 0; 438 description 439 "The number of communication paths traversed 440 between the local clock and the grandmaster clock."; 442 } 443 leaf offset-from-master { 444 type binary { 445 length "1..255"; 446 } 447 description 448 "An implementation-specific representation of the 449 current value of the time difference between a master 450 and a slave clock as computed by the slave."; 451 } 452 leaf mean-path-delay { 453 type binary { 454 length "1..255"; 455 } 456 description 457 "An implementation-specific representation of the 458 current value of the mean propagation time between a 459 master and slave clock as computed by the slave."; 461 } 462 } 464 grouping parent-ds-entry { 465 description 466 "Collection of members of the parent data set."; 468 container parent-port-identity { 469 description 470 "The portIdentity of the port on the master. 471 It contains two members: clockIdentity and portNumer."; 473 leaf clock-identity { 474 type binary { 475 length "8"; 476 } 477 description 478 "The clockIdentity of the master clock."; 479 } 481 leaf port-number { 482 type uint16; 483 description 484 "The portNumber for the port on the specific 485 master."; 486 } 487 } 488 leaf parent-stats { 489 type boolean; 490 default false; 491 description 492 "Indicates whether the values of 493 observedParentOffsetScaledLogVariance and 494 observedParentClockPhaseChangeRate of parentDS 495 have been measured and are valid."; 496 } 497 leaf observed-parent-offset-scaled-log-variance { 498 type uint16; 499 default 0xFFFF; 500 description 501 "An estimate of the parent clock's PTP variance 502 as observed by the slave clock."; 503 } 504 leaf observed-parent-clock-phase-change-rate { 505 type int32; 506 description 507 "An estimate of the parent clock's phase change rate 508 as observed by the slave clock."; 509 } 510 leaf grandmaster-identity { 511 type binary{ 512 length "8"; 514 } 515 description 516 "The clockIdentity attribute of the grandmaster clock."; 518 } 519 container grandmaster-clock-quality { 520 description 521 "The clockQuality of the grandmaster clock. It contains 522 clockClass, clockAccuracy and offsetScaledLogVariance."; 524 leaf grandmaster-clock-class { 525 type uint8; 526 default 248; 527 description 528 "The clockClass attribute of the grandmaster clock."; 530 } 531 leaf grandmaster-clock-accuracy { 532 type uint8; 533 description 534 "The clockAccuracy attribute of the grandmaster 535 clock."; 536 } 537 leaf grandmaster-offset-scaled-log-variance { 538 type uint16; 539 description 540 "The offsetScaledLogVariance of the grandmaster 541 clock."; 542 } 543 } 544 leaf grandmaster-priority1 { 545 type uint8; 546 description 547 "The priority1 attribute of the grandmaster clock."; 549 } 550 leaf grandmaster-priority2 { 551 type uint8; 552 description 553 "The priority2 attribute of the grandmaster clock."; 555 } 557 } 559 grouping time-properties-ds-entry { 560 description 561 "Collection of members of the timeProperties data set."; 563 leaf current-utc-offset-valid { 564 type boolean; 565 description 566 "Indicates whether current UTC offset is valid."; 567 } 568 leaf current-utc-offset { 569 type uint16; 570 description 571 "The offset between TAI and UTC when the epoch of the 572 PTP system is the PTP epoch, otherwise the value has 573 no meaning."; 574 } 575 leaf leap59 { 576 type boolean; 577 description 578 "Indicates whether the last minute of the current UTC 579 day contains 59 seconds."; 580 } 581 leaf leap61 { 582 type boolean; 583 description 584 "Indicates whether the last minute of the current UTC 585 day contains 61 seconds."; 586 } 587 leaf time-traceable { 588 type boolean; 589 description 590 "Indicates whether the timescale and the 591 currentUtcOffset are traceable to a primary 592 reference."; 593 } 594 leaf frequency-traceable { 595 type boolean; 596 description 597 "Indicates whether the frequency determining the 598 timescale is traceable to a primary reference."; 599 } 600 leaf PTP-timescale { 601 type boolean; 602 description 603 "Indicates whether the clock timescale 604 of the grandmaster clock is PTP."; 605 } 606 leaf time-source { 607 type uint8; 608 description 609 "The source of time used by the grandmaster clock."; 611 } 612 } 614 grouping port-ds-entry { 615 description 616 "Collection of members of the port data set."; 618 container port-identity { 619 description 620 "The PortIdentity attribute of the local port. 621 It contains two members: clockIdentity and 622 portNumber."; 624 leaf clock-identity { 625 type binary { 626 length "8"; 627 } 628 description 629 "The clockIdentity of the local clock."; 630 } 632 leaf port-number { 633 type uint16; 634 description 635 "The portNumber for a port on the local clock."; 637 } 638 } 640 leaf port-state { 641 type uint8; 642 default 1; 643 description 644 "Current state associated with the port."; 645 } 647 leaf log-min-delay-req-interval { 648 type int8; 649 description 650 "The logarithm to the base 2 of the minDelayReqInterval 651 (the minimum permitted mean time interval between 652 successive Delay_Req messages)."; 653 } 654 leaf peer-mean-path-delay { 655 type int64; 656 default 0; 657 description 658 "An estimate of the current one-way propagation delay 659 on the link when the delayMechanism is P2P, otherwise 660 it is zero."; 661 } 663 leaf log-announce-interval { 664 type int8; 665 description 666 "The logarithm to the base 2 of the of the mean 667 announceInterval (mean time interval between 668 successive Announce messages)."; 669 } 671 leaf announce-receipt-timeout { 672 type uint8; 673 description 674 "The number of announceInterval that have to pass 675 without receipt of an announce message before the 676 occurrence of the event ANNOUNCE_RECEIPT_TIMEOUT_ 677 EXPIRES."; 678 } 680 leaf log-sync-interval { 681 type int8; 682 description 683 "The logarithm to the base 2 of the mean SyncInterval 684 for multicast messages. The rates for unicast 685 transmissions are negotiated separately on a per port 686 basis."; 687 } 689 leaf delay-mechanism { 690 type enumeration { 691 enum E2E { 692 value 01; 693 description 694 "The port uses the delay request-response 695 mechanism."; 696 } 697 enum P2P { 698 value 02; 699 description 700 "The port uses the peer delay mechanism."; 702 } 703 enum DISABLED { 704 value 254; 705 description 706 "The port does not implement the delay 707 mechanism."; 708 } 709 } 710 description 711 "The propagation delay measuring option used by the 712 port in computing meanPathDelay."; 713 } 715 leaf log-min-Pdelay-req-interval { 716 type int8; 717 description 718 "The logarithm to the base 2 of the 719 minPdelayReqInterval (minimum permitted mean time 720 interval between successive Pdelay_Req messages)."; 722 } 724 leaf version-number { 725 type uint8; 726 description 727 "The PTP version in use on the port."; 728 } 729 } 731 grouping transparent-clock-default-ds-entry { 732 description 733 "Collection of members of the transparentClockDefault data 734 set (default data set for a transparent clock)."; 736 leaf clock-identity { 737 type binary { 738 length "8"; 739 } 740 description 741 "The clockIdentity of the transparent clock."; 742 } 743 leaf number-ports { 744 type uint16; 745 description 746 "The number of PTP ports on the device."; 747 } 748 leaf delay-mechanism { 749 type enumeration { 750 enum E2E { 751 value 1; 752 description 753 "The port uses the delay request-response 754 mechanism."; 755 } 756 enum P2P { 757 value 2; 758 description 759 "The port uses the peer delay mechanism."; 760 } 761 enum DISABLED { 762 value 254; 763 description 764 "The port does not implement the delay 765 mechanism."; 766 } 767 } 768 description 769 "The propagation delay measuring option 770 used by the transparent clock."; 771 } 772 leaf primary-domain { 773 type uint8; 774 default 0; 775 description 776 "The domainNumber of the primary syntonization domain."; 778 } 779 } 781 grouping transparent-clock-port-ds-entry { 782 description 783 "Collection of members of the transparentClockPort data 784 set (port data set for a transparent clock)."; 786 container port-identity { 787 description 788 "This object specifies the portIdentity of the local 789 port."; 791 leaf clock-identity { 792 type binary { 793 length "8"; 794 } 795 description 796 "The clockIdentity of the transparent clock."; 797 } 799 leaf port-number { 800 type uint16; 801 description 802 "The portNumber for a port on the transparent 803 clock."; 804 } 805 } 806 leaf log-min-pdelay-req-interval { 807 type int8; 808 description 809 "The logarithm to the base 2 of the 810 minPdelayReqInterval (minimum permitted mean time 811 interval between successive Pdelay_Req messages)."; 812 } 813 leaf faulty-flag { 814 type boolean; 815 default false; 816 description 817 "Indicates whether the port is faulty."; 818 } 819 leaf peer-mean-path-delay { 820 type int64; 821 default 0; 822 description 823 "An estimate of the current one-way propagation delay 824 on the link when the delayMechanism is P2P, otherwise 825 it is zero."; 826 } 827 } 829 list instance-list { 831 key "instance-number"; 833 description 834 "List of one or more PTP datasets in the device, 835 one for each domain-number (see IEEE 1588-2008 subclause 836 6.3)"; 838 leaf instance-number { 839 type uint8; 840 description 841 "The instance number of the current PTP instance"; 842 } 843 container default-ds { 844 description 845 "The default data set of the clock."; 846 uses default-ds-entry; 847 } 849 container current-ds { 850 description 851 "The current data set of the clock."; 852 uses current-ds-entry; 853 } 855 container parent-ds { 856 description 857 "The parent data set of the clock."; 858 uses parent-ds-entry; 859 } 861 container time-properties-ds { 862 description 863 "The timeProperties data set of the clock."; 864 uses time-properties-ds-entry; 865 } 867 list port-ds-list { 868 key "port-number"; 869 description 870 "List of port data sets of the clock."; 871 leaf port-number{ 872 type leafref{ 873 path "../port-identity/port-number"; 874 } 875 description 876 "Refers to the portNumber memer of 877 portDS.portIdentity."; 878 } 879 uses port-ds-entry; 880 } 881 } 883 container transparent-clock-default-ds { 884 description 885 "The members of the transparentClockDefault Data Set"; 886 uses transparent-clock-default-ds-entry; 887 } 888 list transparent-clock-port-ds-list { 889 key "port-number"; 890 description 891 "List of transparentClockPort data sets 892 of the transparent clock."; 893 leaf port-number { 894 type leafref { 895 path "../port-identity/port-number"; 896 } 897 description 898 "Refers to the portNumber memer 899 of transparentClockPortDS.portIdentity."; 900 } 901 uses transparent-clock-port-ds-entry; 902 } 903 } 904 906 4. Security Considerations 908 YANG modules are designed to be accessed via the NETCONF protocol 909 [RFC6241], thus security considerations in [RFC6241] apply here. 910 Security measures such as using the NETCONF over SSH [RFC6242] and 911 restricting its use with access control [RFC6536] can further 912 improve its security, avoid injection attacks and misuse of the 913 protocol. 915 Some data nodes defined in this YANG module are writable, and any 916 changes to them may adversely impact a synchronization network. 918 5. IANA Considerations 920 This document registers a URI in the IETF XML registry, and the 921 following registration is requested to be made: 922 URI: urn:ietf:params:xml:ns:yang:ietf-ptp-dataset 923 This document registers a YANG module in the YANG Module Names: 924 name: ietf-ptp-dataset namespace: urn:ietf:params:xml:ns:yang:ietf- 925 ptp-dataset 927 6. References 929 6.1. Normative References 931 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 932 Requirement Levels", BCP 14, RFC 2119, March 1997 934 [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the 935 Network Configuration Protocol (NETCONF) ", RFC 6020, 936 October 2010 938 [RFC6991] Schoenwaelder, J., "Common YANG Data Types", RFC 6991, 939 July 2013 941 [IEEE1588] IEEE, "IEEE Standard for a Precision Clock 942 Synchronization Protocol for Networked Measurement and 943 Control Systems", IEEE Std 1588-2008, July 2008 945 6.2. Informative References 947 [IEEE8021AS] IEEE, "Timing and Synchronizations for Time-Sensitive 948 Applications in Bridged Local Area Networks", IEEE 949 802.1AS-2001, 2011 951 [PTP-MIB] Shankarkumar, V., Montini, L., Frost, T., and Dowd, G., 952 "Precision Time Protocol Version 2 (PTPv2) Management 953 Information Base", draft-ietf-tictoc-ptp-mib-11, Work in 954 progress 956 [REST-CONF] Bierman, A., Bjorklund, M., and Watsen, K., "RESTCONF 957 protocol", draft-ietf-netconf-restconf-17, Work in 958 progress 960 [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between 961 Information Models and Data Models", RFC 3444, January 962 2003 964 [RFC4663] Harrington, D., "Transferring MIB Work from IETF Bridge 965 MIB WG to IEEE 802.1 WG", RFC 4663, September 2006 967 [RFC6241] Enns, R., Bjorklund, M., Schoenwaelder, J., and A. 968 Bierman, "Network Configuration Protocol (NETCONF)", RFC 969 6241, June 2011 971 [RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure 972 Shell (SSH)", RFC 6242, June 2011 974 [RFC6536] Bierman, A. and M. Bjorklund, "Network Configuration 975 Protocol (NETCONF) Access Control Model", RFC 6536, March 976 2012 978 7. Acknowledgments 980 The authors would like to thank reviews and suggestions from Mahesh 981 Jethanandani and Tal Mizrahi. 983 Appendix A Transferring YANG Work to IEEE 1588 WG (Informational) 985 This appendix describes a future plan to transition responsibility 986 for IEEE 1588 YANG modules from the IETF TICTOC Working Group (WG) 987 to the IEEE 1588 WG, which develops the time synchronization 988 technology that the YANG modules are designed to manage. 990 This appendix is forward-looking with regard to future 991 standardization roadmaps in IETF and IEEE. Since those roadmaps 992 cannot be predicted with significant accuracy, this appendix is 993 informational, and it does not specify imperatives or normative 994 specifications of any kind. 996 The IEEE 1588-2008 YANG module of this standard represents a 997 cooperation between IETF (for YANG) and IEEE (for 1588). For the 998 initial standardization of IEEE-1588 YANG modules, the information 999 model is relatively clear (i.e. IEEE 1588 data sets), but expertise 1000 in YANG is required, making IETF an appropriate location for the 1001 standards. The TICTOC WG has expertise with IEEE 1588, making it 1002 the appropriate location within IETF. 1004 The IEEE 1588 WG anticipates future changes to its standard on an 1005 ongoing basis. As IEEE 1588 WG members gain practical expertise 1006 with YANG, the IEEE 1588 WG will become more appropriate for 1007 standardization of its YANG modules. As the IEEE 1588 standard is 1008 revised and/or amended, IEEE 1588 members can more effectively 1009 synchronize the revision of this YANG module with future versions 1010 of the IEEE 1588 standard. 1012 This appendix is meant to establish some clear expectations between 1013 IETF and IEEE about the future transfer of IEEE 1588 YANG modules 1014 to the IEEE 1588 WG. The goal is to assist in making the future 1015 transfer as smooth as possible. As the transfer takes place, some 1016 case-by-case situations are likely to arise, which can be handled 1017 by discussion on the IETF TICTOC WG mailing lists and/or 1018 appropriate liaisons. 1020 This appendix obtained insight from [RFC4663], an informational 1021 memo that described a similar transfer of MIB work from the IETF 1022 Bridge MIB WG to the IEEE 802.1 WG. 1024 A.1. Assumptions for the Transfer 1026 For the purposes of discussion in this appendix, assume that the 1027 IETF TICTOC WG has approved a standard YANG module for a published 1028 IEEE 1588 standard. As of this writing, this is IEEE Std 1588-2008, 1029 but it is possible that YANG for subsequent 1588 revisions could be 1030 published from the IETF TICTOC WG. For discussion in this appendix, 1031 we use the phrase "last IETF 1588 YANG" to refer to most recently 1032 published 1588 YANG from the IETF TICTOC WG. 1034 The IEEE-SA Standards Board New Standards Committee (NesCom) 1035 handles new Project Authorization Requests (PARs) (see 1036 http://standards.ieee.org/board/nes/). PARs are roughly the 1037 equivalent of IETF Working Group Charters and include information 1038 concerning the scope, purpose, and justification for 1039 standardization projects. 1041 Assume that IEEE 1588 has an approved PAR that explicitly specifies 1042 development of a YANG module. The transfer of YANG work will occur 1043 in the context of this IEEE 1588 PAR. For discussion in this 1044 appendix, we use the phrase "first IEEE 1588 YANG" to refer to the 1045 first IEEE 1588 standard for YANG. 1047 Assume that as part of the transfer of YANG work, the IETF TICTOC 1048 WG agrees to cease all work on standard YANG modules for IEEE 1588. 1050 Assume that the IEEE 1588 WG has participated in the development of 1051 the last IETF 1588 YANG module, such that the first IEEE 1588 YANG 1052 module will effectively be a revision of it. In other words, the 1053 transfer of YANG work will be relatively clean. 1055 The actual conditions for the future transfer can be such that the 1056 preceding assumptions do not hold. Exceptions to the assumptions 1057 will need to be addressed on a case-by-case basis at the time of 1058 the transfer. This appendix describes topics that can be addressed 1059 based on the preceding assumptions. 1061 A.2. Intellectual Property Considerations 1063 During review of the legal issues associated with transferring 1064 Bridge MIB WG documents to the IEEE 802.1 WG (Section 3.1 and 1065 Section 9 of [RFC4663]), it was concluded that the IETF does not 1066 have sufficient legal authority to make the transfer to IEEE 1067 without the consent of the document authors. 1069 If the last IETF 1588 YANG is published as a RFC, the work is 1070 required to be transferred from the IETF to the IEEE, so that IEEE 1071 1588 WG can begin working on the first IEEE 1588 YANG. 1073 When work on the first IEEE YANG module begins in the IEEE 1588 WG, 1074 that work derives from the last IETF YANG module of this RFC, 1075 requiring a transfer of that work from the IETF to the IEEE. In 1076 order to avoid having the transfer of that work be dependent on the 1077 availability of this RFC's authors at the time of its publication, 1078 the IEEE Standards Association department of Risk Management and 1079 Licensing provided the appropriate forms and mechanisms for this 1080 document's authors to assign a non-exclusive license for IEEE to 1081 create derivative works from this document. Those IEEE forms and 1082 mechanisms will be updated as needed during the development of this 1083 document and any future IETF YANG modules for IEEE 1588. This will 1084 help to make the future transfer of work from IETF to IEEE occur as 1085 smoothly as possible. 1087 As stated in the initial "Status of this Memo", the YANG module in 1088 this document conforms to the provisions of BCP 78. The IETF will 1089 retain all the rights granted at the time of publication in the 1090 published RFCs. 1092 A.3. Namespace and Module Name 1094 As specified in the "IANA Considerations" section, the YANG module 1095 in this document uses IETF as the root of its URN namespace and 1096 YANG module name. 1098 Use of IETF as the root of these names implies that the YANG module 1099 is standardized in a Working Group of IETF, using the IETF 1100 processes. If the IEEE 1588 Working Group were to continue using 1101 these names rooted in IETF, the IEEE 1588 YANG standardization 1102 would need to continue in the IETF. The goal of transferring the 1103 YANG work is to avoid this sort of dependency between standards 1104 organizations. 1106 IEEE 802 has an active PAR (IEEE P802d) for creating a URN 1107 namespace for IEEE use (see 1108 http://standards.ieee.org/develop/project/802d.html). It is likely 1109 that this IEEE 802 PAR will be approved and published prior to the 1110 transfer of YANG work to the IEEE 1588 WG. If so, the IEEE 1588 WG 1111 can use the IEEE URN namespace for the first IEEE 1588 YANG module, 1112 such as: 1114 urn:ieee:Std:1588:yang:ieee1588-ptp-dataset 1116 where "ieee1588-ptp-dataset" is the registered YANG module name in 1117 the IEEE. 1119 Under the assumptions of section A.1, the first IEEE 1588 YANG 1120 module prefix can be the same as the last IETF 1588 YANG module 1121 prefix (i.e. "ptp-dataset"), since the nodes within both YANG 1122 modules are compatible. 1124 The result of these name changes are that for complete 1125 compatibility, a server (i.e. IEEE 1588 node) can choose to 1126 implement a YANG module for the last IETF 1588 YANG module (with 1127 IETF root) as well as the first IEEE 1588 YANG module (with IEEE 1128 root). Since the content of the YANG module transferred are the 1129 same, the server implementation is effectively common for both. 1131 From a client's perspective, a client of the last IETF 1588 YANG 1132 module (or earlier) looks for the IETF-rooted module name; and a 1133 client of the first IEEE 1588 YANG module (or later) looks for the 1134 IEEE-rooted module name. 1136 A.4. IEEE 1588 YANG Modules in ASCII Format 1138 Although IEEE 1588 can certainly decide to publish YANG modules 1139 only in the PDF format that they use for their standard documents, 1140 without publishing an ASCII version, most network management 1141 systems cannot import the YANG module directly from the PDF. Thus, 1142 not publishing an ASCII version of the YANG module would negatively 1143 impact implementers and deployers of YANG modules and would make 1144 potential IETF reviews of YANG modules more difficult. 1146 This appendix recommends that the IEEE 1588 WG consider future 1147 plans for: 1149 o Public availability of the ASCII YANG modules during project 1150 development. These ASCII files allow IETF participants to access 1151 these documents for pre-standard review purposes. 1153 o Public availability of the YANG portion of published IEEE 1588 1154 standards, provided as an ASCII file for each YANG module. 1155 These ASCII files are intended for use of the published IEEE 1156 1588 standard. 1158 As an example of public availability during project development, 1159 IEEE 802 uses the same repository that IETF uses for YANG module 1160 development (see https://github.com/YangModels/yang). IEEE branches 1161 are provided for experimental work (i.e. pre-PAR) as well as 1162 standard work (post-PAR drafts). IEEE-SA has approved use of this 1163 repository for project development, but not for published standards. 1165 As an example of public availability of YANG modules for published 1166 standards, IEEE 802.1 provides a public list of ASCII files for MIB 1167 (see http://www.ieee802.org/1/files/public/MIBs/ and 1168 http://www.ieee802.org/1/pages/MIBS.html), and analogous lists are 1169 planned for IEEE 802.1 YANG files. 1171 Authors' Addresses 1173 Yuanlong Jiang (Editor) 1174 Huawei Technologies Co., Ltd. 1175 Bantian, Longgang district 1176 Shenzhen 518129, China 1177 Email: jiangyuanlong@huawei.com 1179 Xian Liu 1180 Huawei Technologies Co., Ltd. 1181 Bantian, Longgang district 1182 Shenzhen 518129, China 1183 lene.liuxian@huawei.com 1185 Jinchun Xu 1186 Huawei Technologies Co., Ltd. 1187 Bantian, Longgang district 1188 Shenzhen 518129, China 1189 xujinchun@huawei.com 1191 Rodney Cummings (Editor) 1192 National Instruments 1193 11500 N. Mopac Expwy 1194 Bldg. C 1195 Austin, TX 78759-3504 1196 Email: Rodney.Cummings@ni.com