docs/doc/source/system_configuration/kubernetes/ptp-introduction-d981dd710bda.rst

PTP Introduction

As an alternative to services, can be used by nodes to synchronize clocks in a network. It provides:

• more accurate clock synchronization
• the ability to extend the clock synchronization, not only to hosts (controllers, workers, and storage nodes), but also to hosted applications on hosts.

When used in conjunction with hardware support on the and Management network interface cards, is capable of sub-microsecond accuracy. supports the configuration of three services that are used for various configurations: ptp4l, phc2sys and ts2phc.

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 gnss-and-synce-support-62004dc97f3e 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 nodes as well as setting the Hardware Clock (PHC) on the NIC. See man ptp4l 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 or ts2phc, depending on the system configuration. Refer to the man pages (man phc2sys) for a complete list of configuration parameters.

ts2phc

ts2phc synchronizes 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.

Overview of the configuration units

• Instances
  • Each instance represents a service of type ptp4l, phc2sys or ts2phc. 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 node to set the currentUtcOffsetValid flag in its announce messages and to correctly set the CLOCK_TAI on the system. Assign currentUtcOffsetValid=1 at the the ptp4l instance level to set this flag.

    To return the CLOCK_TAI offset to 0, the currentUtcOffsetValid=1 parameter must be removed and the host must be restarted via lock/unlock.

General information

The relevant system locations for instance configuration files are:

/etc/ptpinstance/

Application configuration files, one per instance (excluding clock type).

/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 instance services.

Instances provide several default parameters that can be overwritten by setting a parameter with the same key.

recommends using the system ptp-instance-apply` command to validate your configuration prior to performing any system host-lock/unlock actions, as a bad configuration could result in a configuration failure and trigger additional reboots as the system tries to recover.