PTP Introduction¶
As an alternative to NTP services, PTP can be used by StarlingX nodes to synchronize clocks in a network. It provides:
more accurate clock synchronization
the ability to extend the clock synchronization, not only to StarlingX hosts (controllers, workers, and storage nodes), but also to hosted applications on StarlingX hosts.
When used in conjunction with hardware support on the OAM and Management
network interface cards, PTP is capable of sub-microsecond accuracy. StarlingX
supports the configuration of three services that are used for various PTP
configurations: ptp4l
, phc2sys
and ts2phc
.
StarlingX also supports a ‘clock’ service is used to manage specific NIC
parameters related to Synchronous Ethernet (SyncE) and Pulse Per Second (PPS)
support. Please see SyncE Introduction for information
on the ‘clock’ service. The ptp4l
, phc2sys
and ts2phc
services are
part of the linuxptp project (https://sourceforge.net/projects/linuxptp/).
ptp4l
ptp4l is the implementation of Precision Time Protocol according to the IEEE standard 1588 for Linux. It handles communication between PTP nodes as well as setting the PTP Hardware Clock (PHC) on the NIC. Refer to the man page (man ptp41) for a complete list of configuration parameters.
phc2sys
phc2sys is used to synchronize the system time with a PHC. The PHC may be set by either
ptp4l
orts2phc
, depending on the system configuration. Refer to the man pages (man phc2sys) for a complete list of configuration parameters.ts2phc
ts2phc synchronizes PTP Hardware Clocks (PHC) to external time stamp signals, such as those coming from GNSS. A single source may be used to distribute time to one or more PHC devices. Refer to the man pages (man ts2phc) for a complete list of configuration parameters.
Note
For more information on PTP compatible NICs, see Kubernetes Verified Commercial Hardware.
Overview of the StarlingX configuration units¶
Instances
Each instance represents a service of type
ptp4l
,phc2sys
orts2phc
. There may be multiple instances of each type of service depending on the required configuration.
Interfaces
An interface is assigned to an instance. One or more physical ports on a system may be assigned to an interface. Assigning multiple ports to the same interface allows for them to share the same configuration.
Parameters
Parameters are key/value pairs that represent various program options. The key should exactly match an option from one of the service man pages, but this is not enforced. It is possible to enter invalid parameters which could prevent a service from starting.
Parameters are scoped to an instance or an interface. The commands system ptp-instance-parameter-add and system ptp-interface-parameter-add are used to assign these respectively.
A special instance level parameter called
cmdline_opts
is provided to allow certain parameters to be set which do not have a long name option supported in the configuration file.A special
ptp4l
instance level parameter is provided to allow a PTS node to set thecurrentUtcOffsetValid
flag in its announce messages and to correctly set theCLOCK_TAI
on the system. AssigncurrentUtcOffsetValid=1
at the theptp4l
instance level to set this flag.To return the CLOCK_TAI offset to 0, the
currentUtcOffsetValid=1
parameter must be removed using system ptp-instance-parameter delete and the PTP configuration must be re-applied with system ptp-instance-apply`.
General information¶
The relevant system locations for PTP instance configuration files are:
/etc/linuxptp/ptpinstance/
Application configuration files. A single configuration file is generated for each configured instance.
/etc/sysconfig/ptpinstance
Environment variable files, one per instance
/etc/systemd/system/ptpinstance/
systemd service files, one per instance type (excluding clock type).
/var/log/user.log
log output for PTP instance services.
Instances provide several default parameters that can be overwritten by setting a parameter with the same key.
StarlingX recommends using the system ptp-instance-apply` command to validate your configuration prior to performing any system host-lock/unlock actions, as a bad PTP configuration could result in a configuration failure and trigger additional reboots as the system tries to recover.