Applies to openSUSE Leap 42.1

18 Precision Time Protocol

For network environments, it is vital to keep the computer and other devices' clocks synchronized and accurate. There are several solutions to achieve this, for example the widely used Network Time Protocol (NTP) described in Book “Reference”, Chapter 18 “Time Synchronization with NTP”.

The Precision Time Protocol (PTP) is a protocol capable of sub-microsecond accuracy, which is better than what NTP achieves. PTP support is divided between the kernel and user space. The kernel in openSUSE Leap includes support for PTP clocks, which are provided by network drivers.

18.1 Introduction to PTP

The clocks managed by PTP follow a master-slave hierarchy. The slaves are synchronized to their masters. The hierarchy is updated by the best master clock (BMC) algorithm, which runs on every clock. The clock with only one port can be either master or slave. Such a clock is called an ordinary clock (OC). A clock with multiple ports can be master on one port and slave on another. Such a clock is called a boundary clock (BC). The top-level master is called the grandmaster clock. The grandmaster clock can be synchronized with a Global Positioning System (GPS). This way disparate networks can be synchronized with a high degree of accuracy.

The hardware support is the main advantage of PTP. It is supported by various network switches and network interface controllers (NIC). While it is possible to use non-PTP enabled hardware within the network, having network components between all PTP clocks PTP hardware enabled achieves the best possible accuracy.

18.1.1 PTP Linux Implementation

On SUSE Linux Enterprise Server, the implementation of PTP is provided by the linuxptp package. Install it with zypper install linuxptp. It includes the ptp4l and phc2sys programs for clock synchronization. ptp4l implements the PTP boundary clock and ordinary clock. When hardware time stamping is enabled, ptp4l synchronizes the PTP hardware clock to the master clock. With software time stamping, it synchronizes the system clock to the master clock. phc2sys is needed only with hardware time stamping to synchronize the system clock to the PTP hardware clock on the network interface card (NIC).

18.2 Using PTP

18.2.1 Network Driver and Hardware Support

PTP requires that the used kernel network driver supports either software or hardware time stamping. Moreover, the NIC must support time stamping in the physical hardware. You can verify the driver and NIC time stamping capabilities with ethtool:

ethtool -T eth0
Time stamping parameters for eth0:
Capabilities:
hardware-transmit     (SOF_TIMESTAMPING_TX_HARDWARE)
        software-transmit     (SOF_TIMESTAMPING_TX_SOFTWARE)
        hardware-receive      (SOF_TIMESTAMPING_RX_HARDWARE)
        software-receive      (SOF_TIMESTAMPING_RX_SOFTWARE)
        software-system-clock (SOF_TIMESTAMPING_SOFTWARE)
        hardware-raw-clock    (SOF_TIMESTAMPING_RAW_HARDWARE)
PTP Hardware Clock: 0
Hardware Transmit Timestamp Modes:
        off                   (HWTSTAMP_TX_OFF)
        on                    (HWTSTAMP_TX_ON)
Hardware Receive Filter Modes:
        none                  (HWTSTAMP_FILTER_NONE)
        all                   (HWTSTAMP_FILTER_ALL)

Software time stamping requires the following parameters:

SOF_TIMESTAMPING_SOFTWARE
SOF_TIMESTAMPING_TX_SOFTWARE
SOF_TIMESTAMPING_RX_SOFTWARE

Hardware time stamping requires the following parameters:

SOF_TIMESTAMPING_RAW_HARDWARE
SOF_TIMESTAMPING_TX_HARDWARE
SOF_TIMESTAMPING_RX_HARDWARE

18.2.2 Using ptp4l

ptp4l uses hardware time stamping by default. As root, you need to specify the network interface capable of hardware time stamping with the -i option. The -m tells ptp4l to print its output to the standard output instead of the system's logging facility:

ptp4l -m -i eth0
selected eth0 as PTP clock
port 1: INITIALIZING to LISTENING on INITIALIZE
port 0: INITIALIZING to LISTENING on INITIALIZE
port 1: new foreign master 00a152.fffe.0b334d-1
selected best master clock 00a152.fffe.0b334d
port 1: LISTENING to UNCALIBRATED on RS_SLAVE
master offset -25937 s0 freq +0 path delay       12340
master offset -27887 s0 freq +0 path delay       14232
master offset -38802 s0 freq +0 path delay       13847
master offset -36205 s1 freq +0 path delay       10623
master offset  -6975 s2 freq -30575 path delay   10286
port 1: UNCALIBRATED to SLAVE on MASTER_CLOCK_SELECTED
master offset  -4284 s2 freq -30135 path delay    9892

The master offset value represents the measured offset from the master (in nanoseconds).

The s0, s1, s2 indicators show the different states of the clock servo: s0 is unlocked, s1 is clock step, and s2 is locked. If the servo is in the locked state (s2), the clock will not be stepped (only slowly adjusted) if the pi_offset_const option is set to a negative value in the configuration file (see man 8 ptp4l for more information).

The freq value represents the frequency adjustment of the clock (in parts per billion, ppb).

The path delay value represents the estimated delay of the synchronization messages sent from the master (in nanoseconds).

Port 0 is a Unix domain socket used for local PTP management. Port 1 is the eth0 interface.

INITIALIZING, LISTENING, UNCALIBRATED and SLAVE are examples of port states which change on INITIALIZE, RS_SLAVE, and MASTER_CLOCK_SELECTED events. When the port state changes from UNCALIBRATED to SLAVE, the computer has successfully synchronized with a PTP master clock.

You can enable software time stamping with the -S option.

ptp4l -m -S -i eth3

You can also run ptp4l as a service:

systemctl start ptp4l

In this case, ptp4l reads its options from the /etc/sysconfig/ptp4l file. By default, this file tells ptp4l to read the configuration options from /etc/ptp4l.conf. For more information on ptp4l options and the configuration file settings, see man 8 ptp4l.

To enable the ptp4l service permanently, run the following:

systemctl enable ptp4l

To disable it, run

systemctl disable ptp4l

18.2.3 ptp4l Configuration File

ptp4l can read its configuration from an optional configuration file. As no configuration file is used by default, you need to specify it with -f.

ptp4l -f /etc/ptp4l.conf

The configuration file is divided into sections. The global section (indicated as [global]) sets the program options, clock options and default port options. Other sections are port specific, and they override the default port options. The name of the section is the name of the configured port—for example, [eth0]. An empty port section can be used to replace the command line option.

[global]
verbose               1
time_stamping         software
[eth0]

The example configuration file is an equivalent of the following command's options:

ptp4l -i eth0 -m -S

For a complete list of ptp4l configuration options, see man 8 ptp4l.

18.2.4 Delay Measurement

ptp4l measures time delay in two different ways: peer-to-peer (P2P) or end-to-end (E2E).

P2P

This method is specified with -P.

It reacts to changes in the network environment faster and is more accurate in measuring the delay. It is only used in networks where each port exchanges PTP messages with one other port. P2P needs to be supported by all hardware on the communication path.

E2E

This method is specified with -E. This is the default.

Automatic method selection

This method is specified with -A. The automatic option starts ptp4l in E2E mode, and changes to P2P mode if a peer delay request is received.

Important
Important

All clocks on a single PTP communication path must use the same method to measure the time delay. A warning will be printed if either a peer delay request is received on a port using the E2E mechanism, or an E2E delay request is received on a port using the P2P mechanism.

18.2.5 PTP Management Client: pmc

You can use the pmc client to obtain more detailed information about ptp41. It reads from the standard input—or from the command line—actions specified by name and management ID. Then it sends the actions over the selected transport, and prints any received replies. There are three actions supported: GET retrieves the specified information, SET updates the specified information, and CMD (or COMMAND) initiates the specified event.

By default, the management commands are addressed to all ports. The TARGET command can be used to select a particular clock and port for the subsequent messages. For a complete list of management IDs, run pmc help.

pmc -u -b 0 'GET TIME_STATUS_NP'
sending: GET TIME_STATUS_NP
        90f2ca.fffe.20d7e9-0 seq 0 RESPONSE MANAGMENT TIME_STATUS_NP
                master_offset              283
                ingress_time               1361569379345936841
                cumulativeScaledRateOffset   +1.000000000
                scaledLastGmPhaseChange    0
                gmTimeBaseIndicator        0
                lastGmPhaseChange          0x0000'0000000000000000.0000
                gmPresent                  true
                gmIdentity                 00b058.feef.0b448a

The -b option specifies the boundary hops value in sent messages. Setting it to zero limits the boundary to the local ptp4l instance. Increasing the value will retrieve the messages also from PTP nodes that are further from the local instance. The returned information may include:

stepsRemoved

The number of communication nodes to the grandmaster clock.

offsetFromMaster, master_offset

The last measured offset of the clock from the master clock (nanoseconds).

meanPathDelay

The estimated delay of the synchronization messages sent from the master clock (nanoseconds).

gmPresent

If true, the PTP clock is synchronized to the master clock; the local clock is not the grandmaster clock.

gmIdentity

This is the grandmaster's identity.

For a complete list of pmc command line options, see man 8 pmc.

18.3 Synchronizing the Clocks with phc2sys

Use phc2sys to synchronize the system clock to the PTP hardware clock (PHC) on the network card. The system clock is considered a slave, while the network card a master. PHC itself is synchronized with ptp4l (see Section 18.2, “Using PTP”). Use -s to specify the master clock by device or network interface. Use -w to wait until ptp4l is in a synchronized state.

phc2sys -s eth0 -w

PTP operates in International Atomic Time (TAI), while the system clock uses Coordinated Universal Time (UTC). If you do not specify -w to wait for ptp4l synchronization, you can specify the offset in seconds between TAI and UTC with -O:

phc2sys -s eth0 -O -35

You can run phc2sys as a service as well:

systemctl start phc2sys

In this case, phc2sys reads its options from the /etc/sysconfig/phc2sys file. For more information on phc2sys options, see man 8 phc2sys.

To enable the phc2sys service permanently, run the following:

systemctl enable phc2sys

To disable it, run

systemctl dosable phc2sys

18.3.1 Verifying Time Synchronization

When PTP time synchronization is working properly and hardware time stamping is used, ptp4l and phc2sys output messages with time offsets and frequency adjustments periodically to the system log.

An example of the ptp4l output:

ptp4l[351.358]: selected /dev/ptp0 as PTP clock
ptp4l[352.361]: port 1: INITIALIZING to LISTENING on INITIALIZE
ptp4l[352.361]: port 0: INITIALIZING to LISTENING on INITIALIZE
ptp4l[353.210]: port 1: new foreign master 00a069.eefe.0b442d-1
ptp4l[357.214]: selected best master clock 00a069.eefe.0b662d
ptp4l[357.214]: port 1: LISTENING to UNCALIBRATED on RS_SLAVE
ptp4l[359.224]: master offset       3304 s0 freq      +0 path delay      9202
ptp4l[360.224]: master offset       3708 s1 freq  -28492 path delay      9202
ptp4l[361.224]: master offset      -3145 s2 freq  -32637 path delay      9202
ptp4l[361.224]: port 1: UNCALIBRATED to SLAVE on MASTER_CLOCK_SELECTED
ptp4l[362.223]: master offset       -145 s2 freq  -30580 path delay      9202
ptp4l[363.223]: master offset       1043 s2 freq  -28436 path delay      8972
[...]
ptp4l[371.235]: master offset        285 s2 freq  -28511 path delay      9199
ptp4l[372.235]: master offset        -78 s2 freq  -28788 path delay      9204

An example of the phc2sys output:

phc2sys[616.617]: Waiting for ptp4l...
phc2sys[628.628]: phc offset     66341 s0 freq      +0 delay   2729
phc2sys[629.628]: phc offset     64668 s1 freq  -37690 delay   2726
[...]
phc2sys[646.630]: phc offset      -333 s2 freq  -37426 delay   2747
phc2sys[646.630]: phc offset       194 s2 freq  -36999 delay   2749

ptp4l normally writes messages very frequently. You can reduce the frequency with the summary_interval directive. Its value is an exponent of the 2^N expression. For example, to reduce the output to every 1024 (which equals to 2^10) seconds, add the following line to the /etc/ptp4l.conf file:

summary_interval 10

You can also reduce the frequency of the phc2sys command's updates with the -u summary-updates option.

18.4 Examples of Configurations

This section includes several examples of ptp4l configuration. The examples are not full configuration files but rather minimal list of changes to be done to the specific files. The string ethX stands for the actual network interface name in your setup.

Example 18.1: Slave clock using software time stamping

/etc/sysconfig/ptp4l:

OPTIONS=”-f /etc/ptp4l.conf -i ethX”

No changes made to the distribution /etc/ptp4l.conf.

Example 18.2: Slave clock using hardware time stamping

/etc/sysconfig/ptp4l:

OPTIONS=”-f /etc/ptp4l.conf -i ethX”

/etc/sysconfig/phc2sys:

OPTIONS=”-s ethX -w”

No changes made to the distribution /etc/ptp4l.conf.

Example 18.3: Master clock using hardware time stamping

/etc/sysconfig/ptp4l:

OPTIONS=”-f /etc/ptp4l.conf -i ethX”

/etc/sysconfig/phc2sys:

OPTIONS=”-s CLOCK_REALTIME -c ethX -w”

/etc/ptp4l.conf:

priority1 127
Example 18.4: Master clock using software time stamping (not generally recommended)

/etc/sysconfig/ptp4l:

OPTIONS=”-f /etc/ptp4l.conf -i ethX”

/etc/ptp4l.conf:

priority1 127

18.5 PTP and NTP

NTP and PTP time synchronization tools can coexist, synchronizing time from one to another in both directions.

18.5.1 NTP to PTP Synchronization

When ntpd is used to synchronize the local system clock, you can configure the ptp4l to be the grandmaster clock distributing the time from the local system clock via PTP. Include the priority1 option in /etc/ptp4l.conf:

[global]
priority1 127
[eth0]

Then run ptp4l:

ptp4l -f /etc/ptp4l.conf

When hardware time stamping is used, you need to synchronize the PTP hardware clock to the system clock with phc2sys:

phc2sys -c eth0 -s CLOCK_REALTIME -w

18.5.2 PTP to NTP Synchronization

You can configure ntpd to distribute the time from the system clock synchronized by ptp4l or phc2sys by using the local reference clock driver. Moreover, you need to stop ntpd from adjusting the system clock—do not specify any remote NTP servers in /etc/ntp.conf:

server   127.127.1.0
fudge    127.127.1.0 stratum 0
Note
Note: NTP and DHCP

When the DHCP client command dhclient receives a list of NTP servers, it adds them to NTP configuration by default. To prevent this behavior, set

NETCONFIG_NTP_POLICY=""

in the /etc/sysconfig/network/config file.

Print this page