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