RFC 8575
YANG Data Model for the Precision Time Protocol (PTP)
RFC 8575: YANG Data Model for the Precision Time Protocol (PTP) ✨
Okay bestie, welcome to part 1! 💖 This RFC is all about a YANG data model for PTP, which is the Precision Time Protocol 🕰️✨. It's giving "let's make clock config actually flexible and internet-based" 💅.
Here's the title block tea ☕: it's Request for Comments 8575, written by Y. Jiang (Ed.) from Huawei, X. Liu (Independent), J. Xu from Huawei, and R. Cummings (Ed.) from National Instruments 🎀. It's on the Standards Track 👑, dated May 2019 🌸, and it's an ISSN 2070-1721 document 🦋. It doesn't obsolete or update anything, so it's a fresh start, no cap 🫶.
Abstract
This doc defines a YANG data model for configuring devices and clocks that use PTP as specified in IEEE Std 1588-2008 🧚. It also covers retrieving config info, data sets, and the running states of PTP clocks 💜. The YANG module here conforms to the Network Management Datastore Architecture (NMDA) 🌈.
Status of This Memo
This is an Internet Standards Track document 👑.
This document is a product of the Internet Engineering Task Force (IETF) 💖. It represents the consensus of the IETF community, and it got public review and was approved for publication by the Internet Engineering Steering Group (IESG) ✨. For more on Internet Standards, check out Section 2 of RFC 7841 🍓.
For the current status, any errata, and how to give feedback, go to https://www.rfc-editor.org/info/rfc8575 🔥.
Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the document authors 🌈. All rights reserved 💅.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication 🎀. Please read these carefully, because they spell out your rights and restrictions 🫶. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come without warranty as described in the Simplified BSD License 💀.
Table of Contents
The TOC is basically the map of the whole doc, so here it is in code form 🗺️:
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Conventions Used in This Document . . . . . . . . . . . . 4
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 4
2. IEEE Std 1588-2008 YANG Data Model Hierarchy . . . . . . . . 5
2.1. Interpretations from IEEE 1588 Working Group . . . . . . 7
2.2. Configuration and State . . . . . . . . . . . . . . . . . 8
3. IEEE Std 1588-2008 YANG Module . . . . . . . . . . . . . . . 9
4. Security Considerations . . . . . . . . . . . . . . . . . . . 21
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22
6. References . . . . . . . . . . . . . . . . . . . . . . . . . 22
6.1. Normative References . . . . . . . . . . . . . . . . . . 22
6.2. Informative References . . . . . . . . . . . . . . . . . 23
Appendix A. Transferring YANG Work to the IEEE 1588 WG . . . . . 25
A.1. Assumptions for the Transfer . . . . . . . . . . . . . . 26
A.2. Intellectual Property Considerations . . . . . . . . . . 26
A.3. Namespace and Module Name . . . . . . . . . . . . . . . . 27
A.4. IEEE 1588 YANG Modules in ASCII Format . . . . . . . . . 28
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 29
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 301. Introduction ✨
Okay so, PTP is a synchronization protocol, and IEEE Std 1588-2008 [IEEE1588] is literally everywhere 🌍: carrier networks, industrial networks, automotive networks, and more 🚗. It can give you high precision time sync down to nanoseconds ⏱️🔥. The protocol relies on a PTP engine to decide its own state automatically 🧠, plus a PTP transport layer to carry the timing and quality messages 📦. The config parameters and state data sets in IEEE Std 1588-2008 are numerous 😭.
Per [RFC3444], IEEE Std 1588-2008 already has an information model in its normative specs for the data sets (clause 8 of IEEE Std 1588-2008) 📚. Some standards orgs, including the IETF, have made data models in MIBs (Management Information Bases) for these data sets, like [RFC8173] and [IEEE8021AS] 🦋. Those MIBs are mostly about retrieving state data with the Simple Network Management Protocol (SNMP) 🌸. Also, config of PTP data sets isn't covered in [RFC8173] 🙈.
Some service providers and apps want the management of the IEEE Std 1588-2008 sync network to be more flexible and Internet based 🌐, usually overlaid on their transport networks 🫶. Software-Defined Networking (SDN) is also a big driver, since it needs better config capability for sync networks 🚀.
YANG [RFC7950] is the data modeling language used to model config and state data that network management protocols like the Network Configuration Protocol (NETCONF) [RFC6241] handle 💖. A small set of built-in data types is defined in [RFC7950], and a bunch of common data types is in [RFC6991] 🎀. YANG has Internet-based config, validation, rollback, and more ✨. All of that makes it a super attractive candidate modeling language for IEEE Std 1588-2008 👑.
This document defines a YANG data model for configuring IEEE Std 1588-2008 devices and clocks, plus retrieving state data for IEEE Std 1588-2008 clocks 🧚. The model is based on the PTP data sets specified in [IEEE1588] 📊. Technology-specific PTP info (like what's specifically implemented by a bridge, a router, or a telecom profile) is out of scope for this doc 🙅♀️.
The YANG module here conforms to the Network Management Datastore Architecture (NMDA) [RFC8342] 🌈.
When people actually use this stuff, network products that support sync usually conform to one or more IEEE Std 1588-2008 profiles 💅. Each profile says how IEEE Std 1588-2008 gets used in a given industry (like telecom or automotive) and app 🚗. A profile can require features that are optional in IEEE Std 1588-2008, and it can specify brand new features built on top of it 🌟.
Readers are assumed to already know IEEE Std 1588-2008, btw 🤓. Here's how the IEEE Std 1588-2008 YANG module is expected to be used:
- The IEEE Std 1588-2008 YANG module can be used as is for products that conform to one of the default profiles specified in IEEE Std 1588-2008 💖.
- When the IEEE Std 1588 standard gets revised (like the revision in progress when this doc was written), it will add some new optional features to its data sets 🔄. The YANG module here can be revised and extended to support those features ✨. Also, the YANG "revision" MUST be used to indicate changes to the YANG module in that situation 🫶.
- A profile standard based on IEEE Std 1588-2008 may create a dedicated YANG module for its profile 🎀. The profile's YANG module SHOULD use YANG "import" to import the IEEE Std 1588-2008 YANG module as its foundation 🧱. Then the profile's YANG module SHOULD use YANG "augment" to add any profile-specific enhancements 💜.
- A product that conforms to a profile standard may also create its own YANG module 🌸. The product's YANG module SHOULD "import" the profile's module, and then use YANG "augment" to add any product-specific enhancements 🦋.
1.1. Conventions Used in This Document
Okay this is the important bit about the key words 🚨! The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here 💅.
1.2. Terminology
Most of the terminology here is pulled from [IEEE1588] 📖.
BC Boundary Clock, see Section 3.1.3 of [IEEE1588]
DS Data Set, see Section 8.1.1 of [IEEE1588]
E2E End-to-End, see Section 3.2 of [IEEE1588]
IANA Internet Assigned Numbers Authority
OC Ordinary Clock, see Section 3.1.22 of [IEEE1588]
P2P Peer-to-Peer, see Section 3.2 of [IEEE1588]
PTP Precision Time Protocol, see Section 3.1.28 of [IEEE1588]
TAI International Atomic Time, see Section 3.2 of [IEEE1588]
TC Transparent Clock, see Section 3.1.46 of [IEEE1588]
UTC Coordinated Universal Time, see Section 3.2 of [IEEE1588]PTP data set 🧁: Structured attributes of clocks (an OC, BC, or TC) that are used for PTP decisions and for providing values for PTP message fields. See Section 8 of [IEEE1588] 🎀.
PTP instance 🌷: A PTP implementation in the device (i.e., an OC or BC) represented by a specific PTP data set 💜.
That's part 1 done, bestie! 🌈 More parts are coming, so stay tuned 🫶✨
2. IEEE Std 1588-2008 YANG Data Model Hierarchy ✨
okay so this section is where we look at the hierarchy of the YANG module for IEEE Std 1588-2008 🌸 it covers how you query and configure the device-wide stuff AND the port-specific stuff, plus the clock data sets. main character energy fr 💅
here's what you can query and configure for clocks 🫶
- Clock data set attributes in a clock node, including the following:
current-ds,parent-ds,default-ds,time-properties-ds, andtransparent-clock-default-ds. - Port-specific data set attributes, including the following:
port-dsandtransparent-clock-port-ds.
(quick note bestie: the attribute names match IEEE Std 1588-2008, but they've been switched over to YANG style, so everything is lowercase with dashes between words 🎀)
all the PTP terminology and PTP data set attributes are explained in super deep detail in IEEE Std 1588-2008, so this doc only gives you the outline inside the YANG module 🧚
we usually show YANG modules with a simplified YANG tree diagram [RFC8340] 🦋 this document uses the exact same tree diagram syntax as [RFC8340], so you're literally already set up to read it 💜
module: ietf-ptp
+--rw ptp
+--rw instance-list* [instance-number]
| +--rw instance-number uint32
| +--rw default-ds
| | +--rw two-step-flag? boolean
| | +--ro clock-identity? clock-identity-type
| | +--rw number-ports? uint16
| | +--rw clock-quality
| | | +--rw clock-class? uint8
| | | +--rw clock-accuracy? uint8
| | | +--rw offset-scaled-log-variance? uint16
| | +--rw priority1? uint8
| | +--rw priority2? uint8
| | +--rw domain-number? uint8
| | +--rw slave-only? boolean
| +--rw current-ds
| | +--rw steps-removed? uint16
| | +--rw offset-from-master? time-interval-type
| | +--rw mean-path-delay? time-interval-type
| +--rw parent-ds
| | +--rw parent-port-identity
| | | +--rw clock-identity? clock-identity-type
| | | +--rw port-number? uint16
| | +--rw parent-stats? boolean
| | +--rw observed-parent-offset-scaled-log-variance? uint16
| | +--rw observed-parent-clock-phase-change-rate? int32
| | +--rw grandmaster-identity? clock-identity-type
| | +--rw grandmaster-clock-quality
| | | +--rw clock-class? uint8
| | | +--rw clock-accuracy? uint8
| | | +--rw offset-scaled-log-variance? uint16
| | +--rw grandmaster-priority1? uint8
| | +--rw grandmaster-priority2? uint8
| +--rw time-properties-ds
| | +--rw current-utc-offset-valid? boolean
| | +--rw current-utc-offset? int16
| | +--rw leap59? boolean
| | +--rw leap61? boolean
| | +--rw time-traceable? boolean
| | +--rw frequency-traceable? boolean
| | +--rw ptp-timescale? boolean
| | +--rw time-source? uint8
| +--rw port-ds-list* [port-number]
| +--rw port-number uint16
| +--rw port-state? port-state-enumeration
| +--rw underlying-interface? if:interface-ref
| +--rw log-min-delay-req-interval? int8
| +--rw peer-mean-path-delay? time-interval-type
| +--rw log-announce-interval? int8
| +--rw announce-receipt-timeout? uint8
| +--rw log-sync-interval? int8
| +--rw delay-mechanism? delay-mechanism-enumeration
| +--rw log-min-pdelay-req-interval? int8
| +--rw version-number? uint8
+--rw transparent-clock-default-ds
| +--ro clock-identity? clock-identity-type
| +--rw number-ports? uint16
| +--rw delay-mechanism? delay-mechanism-enumeration
| +--rw primary-domain? uint8
+--rw transparent-clock-port-ds-list* [port-number]
+--rw port-number uint16
+--rw log-min-pdelay-req-interval? int8
+--rw faulty-flag? boolean
+--rw peer-mean-path-delay? time-interval-type2.1. Interpretations from IEEE 1588 Working Group
okay this part is sooo important 🙈 the model we just looked at and the YANG module have some subtle differences from the data set specs in IEEE Std 1588-2008. these differences come from interpretations by the IEEE 1588 Working Group, and they're meant to keep things compatible with future revisions of the IEEE Std 1588 standard 🔮
so in IEEE Std 1588-2008, a single physical product can run multiple PTP clocks (an ordinary, boundary, or transparent clock, iykyk 💀). per IEEE Std 1588-2008 subclause 7.1, each of those clocks runs in its own independent domain. BUT the way multiple PTP domains were organized wasn't super clear in the 1588-2008 data sets 😭
so this document introduces the PTP instance ✨ a PTP instance is a PTP implementation sitting in a device (so an OC or BC) that's represented by one specific PTP data set. every instance runs in exactly one domain 🌈 the instance concept is used exclusively to allow optional support of multiple domains. and the instance number has no usage within PTP messages, so it's just a local label, not something that shows up on the wire 🧚
then there's the transparent clock stuff 🦋 based on statements in IEEE Std 1588-2008 subclauses 8.3.1 and 10.1, most transparent clock products have interpreted the transparent clock data sets as a singleton at the root level of the managed product. and this YANG data model reflects that exact location 💖
2.2. Configuration and State
this bit is all about who gets to touch what 🎀 the information model of IEEE Std 1588-2008 sorts each member of the PTP data sets into one of these three buckets:
- Configurable: Writable by management.
- Dynamic: Read-only to management, and the value is changed by PTP protocol operation.
- Static: Read-only to management, and the value typically does not change.
if you want the details on which bucket a given member belongs in, go check that member's spec in IEEE Std 1588-2008 🔍
okay now the plot twist 😭 under certain circumstances, a member's classification from IEEE Std 1588 can change for a YANG implementation. like, a configurable member might need to become read-only. when that happens, an implementation SHOULD return a warning when someone writes to a read-only member, OR it can use the deviation mechanism to build a new deviation model, as described in Section 7.20.3 of [RFC7950] 👑
bestie, the vibe here is "don't just silently ignore a write." that's the whole point of the warning 🚨
3. IEEE Std 1588-2008 YANG Module
this module imports the typedef "interface-ref" from [RFC8343] 🫶 most attributes are based on the information model defined in [IEEE1588], but their names got glowed up to fit YANG-style naming ✨
<CODE BEGINS> file "ietf-ptp@2019-05-07.yang"
module ietf-ptp {
yang-version 1.1;
namespace "urn:ietf:params:xml:ns:yang:ietf-ptp";
prefix ptp;
import ietf-interfaces {
prefix if;
reference
"RFC 8343: A YANG Data Model for Interface Management";
}
organization
"IETF TICTOC Working Group";
contact
"WG Web: https://datatracker.ietf.org/wg/tictoc/
WG List: <mailto:tictoc@ietf.org>
Editor: Yuanlong Jiang
<mailto:jiangyuanlong@huawei.com>
Editor: Rodney Cummings
<mailto:rodney.cummings@ni.com>";
description
"This YANG module defines a data model for the configuration
of IEEE Std 1588-2008 clocks, and also for retrieval of the state
data of IEEE Std 1588-2008 clocks.";
revision 2019-05-07 {
description
"Initial version";
reference
"RFC 8575: YANG Data Model for the Precision Time Protocol";
}
typedef delay-mechanism-enumeration {
type enumeration {
enum e2e {
value 1;
description
"The port uses the delay request-response mechanism.";
}
enum p2p {
value 2;
description
"The port uses the peer delay mechanism.";
}
enum disabled {
value 254;
description
"The port does not implement any delay mechanism.";
}
}
description
"The propagation-delay measuring option used by the
port. Values for this enumeration are specified
by the IEEE Std 1588 standard exclusively.";
reference
"IEEE Std 1588-2008: 8.2.5.4.4";
}
typedef port-state-enumeration {
type enumeration {
enum initializing {
value 1;
description
"The port is initializing its data sets, hardware, and
communication facilities.";
}
enum faulty {
value 2;
description
"The port is in the fault state.";
}
enum disabled {
value 3;
description
"The port is disabled and is not communicating PTP
messages (other than possibly PTP management
messages).";
}
enum listening {
value 4;
description
"The port is listening for an Announce message.";
}
enum pre-master {
value 5;
description
"The port is in the pre-master state.";
}
enum master {
value 6;
description
"The port is behaving as a master port.";
}
enum passive {
value 7;
description
"The port is in the passive state.";
}
enum uncalibrated {
value 8;
description
"A master port has been selected, but the port is still
in the uncalibrated state.";
}
enum slave {
value 9;
description
"The port is synchronizing to the selected master port.";
}
}
description
"The current state of the protocol engine associated
with the port. Values for this enumeration are specified
by the IEEE Std 1588 standard exclusively.";
reference
"IEEE Std 1588-2008: 8.2.5.3.1, 9.2.5";
}
typedef time-interval-type {
type int64;
description
"Derived data type for time interval, represented in units of
nanoseconds and multiplied by 2^16";
reference
"IEEE Std 1588-2008: 5.3.2";
}
typedef clock-identity-type {
type binary {
length "8";
}
description
"Derived data type to identify a clock";
reference
"IEEE Std 1588-2008: 5.3.4";
}
grouping clock-quality-grouping {
description
"Derived data type for quality of a clock, which contains
clockClass, clockAccuracy, and offsetScaledLogVariance.";
reference
"IEEE Std 1588-2008: 5.3.7";
leaf clock-class {
type uint8;
default "248";
description
"The clockClass denotes the traceability of the time
or frequency distributed by the clock.";
}
leaf clock-accuracy {
type uint8;
description
"The clockAccuracy indicates the expected accuracy
of the clock.";
}
leaf offset-scaled-log-variance {
type uint16;
description
"The offsetScaledLogVariance provides an estimate of
the variations of the clock from a linear timescale
when it is not synchronized to another clock
using the protocol.";
}
}okay bestie, we're picking up mid-way through the port-ds-list 💖 Here's the next chunk of the YANG tree, with everything exactly as written 🎀
container ptp {
description
"The PTP struct containing all attributes of PTP data set,
other optional PTP attributes can be augmented as well.";
list instance-list {
key "instance-number";
description
"List of one or more PTP data sets in the device (see IEEE
Std 1588-2008 subclause 6.3).
Each PTP data set represents a distinct instance of
PTP implementation in the device (i.e., distinct
Ordinary Clock or Boundary Clock).";
leaf instance-number {
type uint32;
description
"The instance number of the current PTP instance.
This instance number is used for management purposes
only. This instance number does not represent the PTP
domain number and is not used in PTP messages.";
}
container default-ds {
description
"The default data set of the clock (see IEEE Std
1588-2008 subclause 8.2.1). This data set represents
the configuration/state required for operation
of Precision Time Protocol (PTP) state machines.";
reference
"IEEE Std 1588-2008: 8.2.1";
leaf two-step-flag {
type boolean;
description
"When set to true, the clock is a two-step clock;
otherwise,the clock is a one-step clock.";
}
leaf clock-identity {
type clock-identity-type;
config false;
description
"The clockIdentity of the local clock.";
}
leaf number-ports {
type uint16;
description
"The number of PTP ports on the instance.";
}
container clock-quality {
description
"The clockQuality of the local clock.";
uses clock-quality-grouping;
}
leaf priority1 {
type uint8;
description
"The priority1 attribute of the local clock.";
}
leaf priority2 {
type uint8;
description
"The priority2 attribute of the local clock.";
}
leaf domain-number {
type uint8;
description
"The domain number of the current syntonization
domain.";
}
leaf slave-only {
type boolean;
description
"When set to true, the clock is a slave-only clock.";
}
}
container current-ds {
description
"The current data set of the clock (see IEEE Std
1588-2008 subclause 8.2.2). This data set represents
local states learned from the exchange of
Precision Time Protocol (PTP) messages.";
reference
"IEEE Std 1588-2008: 8.2.2";
leaf steps-removed {
type uint16;
default "0";
description
"The number of communication paths traversed
between the local clock and the grandmaster clock.";
}
leaf offset-from-master {
type time-interval-type;
description
"The current value of the time difference between
a master and a slave clock as computed by the slave.";
}
leaf mean-path-delay {
type time-interval-type;
description
"The current value of the mean propagation time between
a master and a slave clock as computed by the slave.";
}
}
container parent-ds {
description
"The parent data set of the clock (see IEEE Std 1588-2008
subclause 8.2.3).";
reference
"IEEE Std 1588-2008: 8.2.3";
container parent-port-identity {
description
"The portIdentity of the port on the master, it
contains two members: clockIdentity and portNumber.";
reference
"IEEE Std 1588-2008: 5.3.5";
leaf clock-identity {
type clock-identity-type;
description
"Identity of the clock.";
}
leaf port-number {
type uint16;
description
"Port number.";
}
}
leaf parent-stats {
type boolean;
default "false";
description
"When set to true, the values of
observedParentOffsetScaledLogVariance and
observedParentClockPhaseChangeRate of parentDS
have been measured and are valid.";
}
leaf observed-parent-offset-scaled-log-variance {
type uint16;
default "65535";
description
"An estimate of the parent clock's PTP variance
as observed by the slave clock.";
}
leaf observed-parent-clock-phase-change-rate {
type int32;
description
"An estimate of the parent clock's phase change rate
as observed by the slave clock.";
}
leaf grandmaster-identity {
type clock-identity-type;
description
"The clockIdentity attribute of the grandmaster clock.";
}
container grandmaster-clock-quality {
description
"The clockQuality of the grandmaster clock.";
uses clock-quality-grouping;
}
leaf grandmaster-priority1 {
type uint8;
description
"The priority1 attribute of the grandmaster clock.";
}
leaf grandmaster-priority2 {
type uint8;
description
"The priority2 attribute of the grandmaster clock.";
}
}
container time-properties-ds {
description
"The timeProperties data set of the clock (see
IEEE Std 1588-2008 subclause 8.2.4).";
reference
"IEEE Std 1588-2008: 8.2.4";
leaf current-utc-offset-valid {
type boolean;
description
"When set to true, the current UTC offset is valid.";
}
leaf current-utc-offset {
when "../current-utc-offset-valid='true'";
type int16;
description
"The offset between TAI and UTC when the epoch of the
PTP system is the PTP epoch in units of seconds, i.e.,
when ptp-timescale is TRUE; otherwise, the value has
no meaning.";
}
leaf leap59 {
type boolean;
description
"When set to true, the last minute of the current UTC
day contains 59 seconds.";
}
leaf leap61 {
type boolean;
description
"When set to true, the last minute of the current UTC
day contains 61 seconds.";
}
leaf time-traceable {
type boolean;
description
"When set to true, the timescale and the
currentUtcOffset are traceable to a primary
reference.";
}
leaf frequency-traceable {
type boolean;
description
"When set to true, the frequency determining the
timescale is traceable to a primary reference.";
}
leaf ptp-timescale {
type boolean;
description
"When set to true, the clock timescale of the
grandmaster clock is PTP; otherwise, the timescale is
ARB (arbitrary).";
}
leaf time-source {
type uint8;
description
"The source of time used by the grandmaster clock.";
}
}
list port-ds-list {
key "port-number";
description
"List of port data sets of the clock (see IEEE Std
1588-2008 subclause 8.2.5).";
reference
"IEEE Std 1588-2008: 8.2.5";
leaf port-number {
type uint16;
description
"Port number.
The data sets (i.e., information model) of IEEE Std
1588-2008 specify a member portDS.portIdentity, which
uses a typed struct with members clockIdentity and
portNumber.";that's the end of this chunk, and the next part picks up right from the port-number description 🦋✨
In this YANG data model, portIdentity is not modeled
in the port-ds-list. However, its members are provided
as follows:
portIdentity.portNumber is provided as this
port-number leaf in port-ds-list, and
portIdentity.clockIdentity is provided as the
clock-identity leaf in default-ds of the instance
(i.e., ../../default-ds/clock-identity).";
}
leaf port-state {
type port-state-enumeration;
default "initializing";
description
"Current state associated with the port.";
}
leaf underlying-interface {
type if:interface-ref;
description
"Reference to the configured underlying interface that
is used by this PTP port (see RFC 8343).";
reference
"RFC 8343: A YANG Data Model for Interface Management";
}
leaf log-min-delay-req-interval {
type int8;
description
"The base-2 logarithm of the minDelayReqInterval
(the minimum permitted mean time interval between
successive Delay_Req messages).";
}
leaf peer-mean-path-delay {
type time-interval-type;
default "0";
description
"An estimate of the current one-way propagation delay
on the link when the delayMechanism is P2P; otherwise,
it is zero.";
}
leaf log-announce-interval {
type int8;
description
"The base-2 logarithm of the mean
announceInterval (mean time interval between
successive Announce messages).";
}
leaf announce-receipt-timeout {
type uint8;
description
"The number of announceIntervals that have to pass
without receipt of an Announce message before the
occurrence of the event ANNOUNCE_RECEIPT_TIMEOUT_
EXPIRES.";
}
leaf log-sync-interval {
type int8;
description
"The base-2 logarithm of the mean SyncInterval
for multicast messages. The rates for unicast
transmissions are negotiated separately on a per-port
basis and are not constrained by this attribute.";
}
leaf delay-mechanism {
type delay-mechanism-enumeration;
description
"The propagation delay measuring option used by the
port in computing meanPathDelay.";
}
leaf log-min-pdelay-req-interval {
type int8;
description
"The base-2 logarithm of the
minPdelayReqInterval (minimum permitted mean time
interval between successive Pdelay_Req messages).";
}
leaf version-number {
type uint8;
description
"The PTP version in use on the port.";
}
}
}
container transparent-clock-default-ds {
description
"The members of the transparentClockDefault data set (see
IEEE Std 1588-2008 subclause 8.3.2).";
reference
"IEEE Std 1588-2008: 8.3.2";
leaf clock-identity {
type clock-identity-type;
config false;
description
"The clockIdentity of the transparent clock.";
}
leaf number-ports {
type uint16;
description
"The number of PTP ports on the transparent clock.";
}
leaf delay-mechanism {
type delay-mechanism-enumeration;
description
"The propagation delay measuring option
used by the transparent clock.";
}
leaf primary-domain {
type uint8;
default "0";
description
"The domainNumber of the primary syntonization domain (see
IEEE Std 1588-2008 subclause 10.1).";
reference
"IEEE Std 1588-2008: 10.1";
}
}
list transparent-clock-port-ds-list {
key "port-number";
description
"List of transparentClockPort data sets of the transparent
clock (see IEEE Std 1588-2008 subclause 8.3.3).";
reference
"IEEE Std 1588-2008: 8.3.3";
leaf port-number {
type uint16;
description
"Port number.
The data sets (i.e., information model) of IEEE Std
1588-2008 specify a member
transparentClockPortDS.portIdentity, which uses a typed
struct with members clockIdentity and portNumber.
In this YANG data model, portIdentity is not modeled in
the transparent-clock-port-ds-list. However, its
members are provided as follows:
portIdentity.portNumber is provided as this leaf member
in transparent-clock-port-ds-list and
portIdentity.clockIdentity is provided as the
clock-identity leaf in transparent-clock-default-ds
(i.e., ../../transparent-clock-default-ds/clock-
identity).";
}
leaf log-min-pdelay-req-interval {
type int8;
description
"The logarithm to the base 2 of the
minPdelayReqInterval (minimum permitted mean time
interval between successive Pdelay_Req messages).";
}
leaf faulty-flag {
type boolean;
default "false";
description
"When set to true, the port is faulty.";
}
leaf peer-mean-path-delay {
type time-interval-type;
default "0";
description
"An estimate of the current one-way propagation delay
on the link when the delayMechanism is P2P; otherwise,
it is zero.";
}
}
}
}
<CODE ENDS>4. Security Considerations 🔒
okay, security time and I'm not going to be chill about it 😭 The YANG module in this doc is a schema for data that's meant to be reached through network management protocols like NETCONF [RFC6241] or RESTCONF [RFC8040]. The lowest NETCONF layer is the secure transport layer, and the mandatory-to-implement secure transport there is Secure Shell (SSH) [RFC6242]. The lowest RESTCONF layer is HTTPS, and the mandatory-to-implement secure transport there is TLS [RFC8446]. General security considerations of time protocols are covered in [RFC7384], so go read that too 🧚
The Network Configuration Access Control Model (NACM) [RFC8341] is how you restrict access for particular NETCONF or RESTCONF users to a preconfigured subset of all the available NETCONF or RESTCONF protocol operations and content. It's giving lockdown energy and we love that for us 💅
There are a number of writable data nodes in this YANG module, and the sensitive subtrees include:
/ptp/instance-listspecifies an instance (i.e., PTP data sets) for an OC or BC./ptp/transparent-clock-default-dsspecifies a default data set for a TC./ptp/transparent-clock-port-ds-listspecifies a list of port data sets for a TC.
Write operations (e.g., edit-config) to these data nodes without proper protection can have a negative effect on network operations. Specifically, an inappropriate configuration of them may adversely impact a PTP synchronization network. For example, loss of synchronization on a clock, accuracy degradation on a set of clocks, or even break down of a whole synchronization network. 💀 This is the part where we all go quiet and protect our clocks.
5. IANA Considerations 🌸
This document registers the following URI in the "IETF XML Registry" [RFC3688]:
URI: urn:ietf:params:xml:ns:yang:ietf-ptp
Registrant Contact: The IESG
XML: N/A; the requested URI is an XML namespaceThis document also registers the following YANG module in the "YANG Module Names" registry [RFC6020]:
Name: ietf-ptp
Namespace: urn:ietf:params:xml:ns:yang:ietf-ptp
Prefix: ptp
Reference: RFC 85756. References 📚
6.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
DOI 10.17487/RFC3688, January 2004,
<https://www.rfc-editor.org/info/rfc3688>.
[RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for
the Network Configuration Protocol (NETCONF)", RFC 6020,
DOI 10.17487/RFC6020, October 2010,
<https://www.rfc-editor.org/info/rfc6020>.
[RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed.,
and A. Bierman, Ed., "Network Configuration Protocol
(NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011,
<https://www.rfc-editor.org/info/rfc6241>.
[RFC6242] Wasserman, M., "Using the NETCONF Protocol over Secure
Shell (SSH)", RFC 6242, DOI 10.17487/RFC6242, June 2011,
<https://www.rfc-editor.org/info/rfc6242>.
[RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types",
RFC 6991, DOI 10.17487/RFC6991, July 2013,
<https://www.rfc-editor.org/info/rfc6991>.
[RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language",
RFC 7950, DOI 10.17487/RFC7950, August 2016,
<https://www.rfc-editor.org/info/rfc7950>.
[RFC8040] Bierman, A., Bjorklund, M., and K. Watsen, "RESTCONF
Protocol", RFC 8040, DOI 10.17487/RFC8040, January 2017,
<https://www.rfc-editor.org/info/rfc8040>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8341] Bierman, A. and M. Bjorklund, "Network Configuration
Access Control Model", STD 91, RFC 8341,
DOI 10.17487/RFC8341, March 2018,
<https://www.rfc-editor.org/info/rfc8341>.
[RFC8342] Bjorklund, M., Schoenwaelder, J., Shafer, P., Watsen, K.,
and R. Wilton, "Network Management Datastore Architecture
(NMDA)", RFC 8342, DOI 10.17487/RFC8342, March 2018,
<https://www.rfc-editor.org/info/rfc8342>.
[RFC8343] Bjorklund, M., "A YANG Data Model for Interface
Management", RFC 8343, DOI 10.17487/RFC8343, March 2018,
<https://www.rfc-editor.org/info/rfc8343>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>.
[IEEE1588] IEEE, "IEEE Standard for a Precision Clock Synchronization
Protocol for Networked Measurement and Control Systems",
IEEE Std 1588-2008, DOI 10.1109/IEEESTD.2008.4579760, July
2008.6.2. Informative References
- [IEEE8021AS] IEEE, "IEEE Standard for Local and Metropolitan Area Networks - Timing and Synchronizations for Time-Sensitive Applications in Bridged Local Area Networks", IEEE 802.1AS-2001. 🌊
- [RFC3444] Pras, A. and J. Schoenwaelder, "On the Difference between Information Models and Data Models", RFC 3444, DOI 10.17487/RFC3444, January 2003,
<https://www.rfc-editor.org/info/rfc3444>. 📚 - [RFC4663] Harrington, D., "Transferring MIB Work from IETF Bridge MIB WG to IEEE 802.1 WG", RFC 4663, DOI 10.17487/RFC4663, September 2006,
<https://www.rfc-editor.org/info/rfc4663>. 🔁 - [RFC7384] Mizrahi, T., "Security Requirements of Time Protocols in Packet Switched Networks", RFC 7384, DOI 10.17487/RFC7384, October 2014,
<https://www.rfc-editor.org/info/rfc7384>. 🔐 - [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018,
<https://www.rfc-editor.org/info/rfc8340>. 🌳 - [RFC8173] Shankarkumar, V., Montini, L., Frost, T., and G. Dowd, "Precision Time Protocol Version 2 (PTPv2) Management Information Base", RFC 8173, DOI 10.17487/RFC8173, June 2017,
<https://www.rfc-editor.org/info/rfc8173>. ⏰
Appendix A. Transferring YANG Work to the IEEE 1588 WG ✨
This Appendix is informational. 🎀
This appendix describes a future plan to transition responsibility for IEEE Std 1588 YANG modules from the IETF TICTOC Working Group (WG) to the IEEE 1588 WG, which develops the time synchronization technology that the YANG modules are designed to manage. It's basically a handoff plan, bestie. 🤝
This appendix is forward-looking with regard to future standardization roadmaps in the IETF and IEEE. Since those roadmaps cannot be predicted with significant accuracy, this appendix is informational, and it does not specify imperatives or normative specifications of any kind. So no strict rules here, just vibes and plans. 🔮
The IEEE Std 1588-2008 YANG module of this standard represents a cooperation between the IETF (for YANG) and IEEE (for 1588). For the initial standardization of IEEE-1588 YANG modules, the information model is relatively clear (i.e., IEEE Std 1588 data sets), but expertise in YANG is required, making IETF an appropriate location for the standards. The TICTOC WG has expertise with IEEE Std 1588, making it the appropriate location within the IETF. It's a true team-up, iykyk. 👯♀️
The IEEE 1588 WG anticipates future changes to its standard on an ongoing basis. As IEEE 1588 WG members gain practical expertise with YANG, the IEEE 1588 WG will become more appropriate for standardization of its YANG modules. As the IEEE 1588 standard is revised and/or amended, IEEE 1588 members can more effectively synchronize the revision of this YANG module with future versions of the IEEE 1588 standard. Growth arc, literally. 🌱
This appendix is meant to establish some clear expectations between IETF and IEEE about the future transfer of IEEE 1588 YANG modules to the IEEE 1588 WG. The goal is to assist in making the future transfer as smooth as possible. As the transfer takes place, some case-by-case situations are likely to arise, which can be handled by discussion on the IETF TICTOC WG mailing lists and/or appropriate liaisons. Expect the unexpected, but make it a group chat. 💬
This appendix obtained insight from [RFC4663], an informational memo that described a similar transfer of MIB work from the IETF Bridge MIB WG to the IEEE 802.1 WG. Same playbook, different WG, lowkey iconic. 📖
A.1. Assumptions for the Transfer
For the purposes of discussion in this appendix, assume that the IESG has approved the publication of an RFC containing a YANG module for a published IEEE 1588 standard. As of this writing, this is IEEE Std 1588-2008, but it is possible that YANG modules for subsequent 1588 revisions could be published from the IETF TICTOC WG. For discussion in this appendix, we use the phrase "last IETF 1588 YANG" to refer to the most recently published 1588 YANG module from the IETF TICTOC WG. 🗂️
The IEEE-SA Standards Board New Standards Committee (NesCom) handles new Project Authorization Requests (PARs) (see <http://standards.ieee.org/board/nes/>). PARs are roughly the equivalent of IETF Working Group Charters and include information concerning the scope, purpose, and justification for standardization projects. Think of PARs as the IEEE's version of a WG charter, periodt. 📝
Assume that IEEE 1588 has an approved PAR that explicitly specifies development of a YANG module. The transfer of YANG work will occur in the context of this IEEE 1588 PAR. For discussion in this appendix, we use the phrase "first IEEE 1588 YANG" to refer to the first IEEE 1588 standard for YANG. 🚀
Assume that as part of the transfer of YANG work, the IETF TICTOC WG agrees to cease all work on standard YANG modules for IEEE 1588. 🫡
Assume that the IEEE 1588 WG has participated in the development of the last IETF 1588 YANG module, such that the first IEEE 1588 YANG module will effectively be a revision of it. In other words, the transfer of YANG work will be relatively clean. ✨
The actual conditions for the future transfer can be such that the preceding assumptions do not hold. Exceptions to the assumptions will need to be addressed on a case-by-case basis at the time of the transfer. This appendix describes topics that can be addressed based on the preceding assumptions. Plans can change, so we'll handle the plot twists when they show up. 🎭
A.2. Intellectual Property Considerations
During review of the legal issues associated with transferring Bridge MIB WG documents to the IEEE 802.1 WG (Sections 3.1 and 9 of [RFC4663]), it was concluded that the IETF does not have sufficient legal authority to make the transfer to the IEEE without the consent of the document authors. Consent first, always. 🙅♀️➡️🤝
If the last IETF 1588 YANG is published as an RFC, the work is required to be transferred from the IETF to the IEEE, so that IEEE 1588 WG can begin working on the first IEEE 1588 YANG. 📦
When work on the first IEEE YANG module begins in the IEEE 1588 WG, that work derives from the last IETF YANG module of this RFC, requiring a transfer of that work from the IETF to the IEEE. In order to avoid having the transfer of that work be dependent on the availability of this RFC's authors at the time of its publication, the IEEE Standards Association department of Risk Management and Licensing provided the appropriate forms and mechanisms for this document's authors to assign a non-exclusive license for IEEE to create derivative works from this document. Those IEEE forms and mechanisms will be updated as needed for any future IETF YANG modules for IEEE 1588 (the signed forms are held by the IEEE Standards Association department of Risk Management and Licensing.). This will help to make the future transfer of work from the IETF to the IEEE occur as smoothly as possible. Paperwork so the authors don't have to be on call forever. 📝💅
As stated in the initial "Status of this Memo", the YANG module in this document conforms to the provisions of BCP 78. The IETF will retain all the rights granted at the time of publication in the published RFCs. Rights stay put, bestie. 🔒
A.3. Namespace and Module Name
As specified in Section 5 "IANA Considerations", the YANG module in this document uses IETF as the root of its URN namespace and YANG module name. 🏷️
Use of IETF as the root of these names implies that the YANG module is standardized in a Working Group of IETF, using the IETF processes. If the IEEE 1588 Working Group were to continue using these names rooted in IETF, the IEEE 1588 YANG standardization would need to continue in the IETF. The goal of transferring the YANG work is to avoid this sort of dependency between standards organizations. Naming is a whole power move. 👑
IEEE 802 has an active PAR (IEEE P802d) for creating a URN namespace for IEEE use (see <http://standards.ieee.org/develop/project/802d.html>). It is likely that this IEEE 802 PAR will be approved and published prior to the transfer of YANG work to the IEEE 1588 WG. If so, the IEEE 1588 WG can use the IEEE URN namespace for the first IEEE 1588 YANG module, such as:
urn:ieee:Std:1588:yang:ieee1588-ptpwhere "ieee1588-ptp" is the registered YANG module name in the IEEE. 🧚
Under the assumptions of Appendix A.1, the first IEEE 1588 YANG module's prefix will be the same as the last IETF 1588 YANG module's prefix (i.e., "ptp"). Consequently, other YANG modules can preserve the same import prefix "ptp" to access PTP nodes during the migration from the last IETF 1588 YANG module to the first IEEE 1588 YANG module. Same prefix, no drama. 💜
The result of these name changes are that for complete compatibility, a server (i.e., IEEE 1588 node) can choose to implement a YANG module for the last IETF 1588 YANG module (with IETF root) as well as the first IEEE 1588 YANG module (with IEEE root). Since the content of the YANG module transferred are the same, the server implementation is effectively common for both. Two names, one implementation, very efficient. 🌸
From a client's perspective, a client of the last IETF 1588 YANG module (or earlier) looks for the IETF-rooted module name; and a client of the first IEEE 1588 YANG module (or later) looks for the IEEE-rooted module name. So clients just look for the name that matches their version. 🎯
A.4. IEEE 1588 YANG Modules in ASCII Format
Although IEEE 1588 can certainly decide to publish YANG modules only in the PDF format that they use for their standard documents, without publishing an ASCII version, most network management systems cannot import the YANG module directly from the PDF. Thus, not publishing an ASCII version of the YANG module would negatively impact implementers and deployers of YANG modules and would make potential IETF reviews of YANG modules more difficult. PDFs are not it, bestie. 📄🙈
This appendix recommends that the IEEE 1588 WG consider future plans for:
- Public availability of the ASCII YANG modules during project development. These ASCII files allow IETF participants to access these documents for pre-standard review purposes. 🔍
- Public availability of the YANG portion of published IEEE 1588 standards, provided as an ASCII file for each YANG module. These ASCII files are intended for use of the published IEEE 1588 standard. 🦋
As an example of public availability during project development, IEEE 802 uses the same repository that IETF uses for YANG module development (see <https://github.com/YangModels/yang>). IEEE branches are provided for experimental work (i.e., pre-PAR) as well as standard work (post-PAR drafts). IEEE-SA has approved use of this repository for project development, but not for published standards. Shared repo, separate lanes. 🛠️
As an example of public availability of YANG modules for published standards, IEEE 802.1 provides a public list of ASCII files for MIB (see <http://www.ieee802.org/1/files/public/MIBs/> and <http://www.ieee802.org/1/pages/MIBS.html>), and analogous lists are planned for IEEE 802.1 YANG files. Lists are planned, so the vibes are looking good. 🌈
Acknowledgments ✨
The authors would like to thank Tom Petch, Radek Krejci, Mahesh Jethanandani, Tal Mizrahi, Opher Ronen, Liang Geng, Alex Campbell, Joe Gwinn, John Fletcher, William Zhao, and Dave Thaler for their valuable reviews and suggestions. They would like to thank Benoit Claise and Radek Krejci for their validation of the YANG module, and thank Jingfei Lv and Zitao Wang for their discussions on IEEE 1588 and YANG, respectively. Huge thank-yous to the whole squad, you all are literally the reason this slays. 🫶💖
Authors' Addresses ✨
Okay bestie, here are the humans behind this spec, and they're all giving main character energy 💅🦋 Yuanlong Jiang and Rodney Cummings are the editors, and the whole crew is very reachable 💌
Yuanlong Jiang (editor) 🎀
Yuanlong Jiang (editor)
Huawei
Bantian, Longgang district
Shenzhen 518129
China
Email: jiangyuanlong@huawei.comXian Liu 🌸
Xian Liu
Independent
Shenzhen 518129
China
Email: lene.liuxian@foxmail.comJinchun Xu 🧚
Jinchun Xu
Huawei
Bantian, Longgang district
Shenzhen 518129
China
Email: xujinchun@huawei.comRodney Cummings (editor) 👑
Rodney Cummings (editor)
National Instruments
11500 N. Mopac Expwy Bldg. C
Austin, TX 78759-3504
United States of America
Email: Rodney.Cummings@ni.comThat's the whole squad, periodt! 🌈✨
📦 where this page comes from
- ietf: rfc8575 2019-05
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms