Red Hat Training

A Red Hat training course is available for Red Hat Enterprise Linux

Chapter 20. Configuring PTP Using ptp4l

20.1. Introduction to PTP

The Precision Time Protocol (PTP) is a protocol used to synchronize clocks in a network. When used in conjunction with hardware support, PTP is capable of sub-microsecond accuracy, which is far better than is normally obtainable with NTP. PTP support is divided between the kernel and user space. The kernel in Red Hat Enterprise Linux includes support for PTP clocks, which are provided by network drivers. The actual implementation of the protocol is known as linuxptp, a PTPv2 implementation according to the IEEE standard 1588 for Linux.

The linuxptp package includes the ptp4l and phc2sys programs for clock synchronization. The ptp4l program implements the PTP boundary clock and ordinary clock. With hardware time stamping, it is used to synchronize the PTP hardware clock to the master clock, and with software time stamping it synchronizes the system clock to the master clock. The phc2sys program is needed only with hardware time stamping, for synchronizing the system clock to the PTP hardware clock on the network interface card (NIC).

20.1.1. Understanding PTP

The clocks synchronized by PTP are organized in a master-slave hierarchy. The slaves are synchronized to their masters which may be slaves to their own masters. The hierarchy is created and updated automatically by the best master clock (BMC) algorithm, which runs on every clock. When a clock has only one port, it can be 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, which can be synchronized by using a Global Positioning System (GPS) time source. By using a GPS-based time source, disparate networks can be synchronized with a high-degree of accuracy.

Figure 20.1. PTP grandmaster, boundary, and slave Clocks

An illustration showing PTP grandmaster

20.1.2. Advantages of PTP

One of the main advantages that PTP has over the Network Time Protocol (NTP) is hardware support present in various network interface controllers (NIC) and network switches. This specialized hardware allows PTP to account for delays in message transfer, and greatly improves the accuracy of time synchronization. While it is possible to use non-PTP enabled hardware components within the network, this will often cause an increase in jitter or introduce an asymmetry in the delay resulting in synchronization inaccuracies, which add up with multiple non-PTP aware components used in the communication path. To achieve the best possible accuracy, it is recommended that all networking components between PTP clocks are PTP hardware enabled. Time synchronization in larger networks where not all of the networking hardware supports PTP might be better suited for NTP.

With hardware PTP support, the NIC has its own on-board clock, which is used to time stamp the received and transmitted PTP messages. It is this on-board clock that is synchronized to the PTP master, and the computer’s system clock is synchronized to the PTP hardware clock on the NIC. With software PTP support, the system clock is used to time stamp the PTP messages and it is synchronized to the PTP master directly. Hardware PTP support provides better accuracy since the NIC can time stamp the PTP packets at the exact moment they are sent and received while software PTP support requires additional processing of the PTP packets by the operating system.

20.2. Using PTP

In order to use PTP, the kernel network driver for the intended interface has to support either software or hardware time stamping capabilities.

20.2.1. Checking for Driver and Hardware Support

In addition to hardware time stamping support being present in the driver, the NIC must also be capable of supporting this functionality in the physical hardware. The best way to verify the time stamping capabilities of a particular driver and NIC is to use the ethtool utility to query the interface. In this example, eth3 is the interface you want to check: 

~]# ethtool -T eth3
Time stamping parameters for eth3:
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)
Note

The PTP Hardware Clock value printed by ethtool is the index of the PTP hardware clock. It corresponds to the naming of the /dev/ptp* devices. The first PHC has an index of 0.

For software time stamping support, the parameters list should include:

  • SOF_TIMESTAMPING_SOFTWARE
  • SOF_TIMESTAMPING_TX_SOFTWARE
  • SOF_TIMESTAMPING_RX_SOFTWARE

For hardware time stamping support, the parameters list should include:

  • SOF_TIMESTAMPING_RAW_HARDWARE
  • SOF_TIMESTAMPING_TX_HARDWARE
  • SOF_TIMESTAMPING_RX_HARDWARE

20.2.2. Installing PTP

The kernel in Red Hat Enterprise Linux includes support for PTP. User space support is provided by the tools in the linuxptp package. To install linuxptp, issue the following command as root: 

~]# yum install linuxptp

This will install ptp4l and phc2sys.

Do not run more than one service to set the system clock’s time at the same time. If you intend to serve PTP time using NTP, see Section 20.8, “Serving PTP Time with NTP”.

20.2.3. Starting ptp4l

The ptp4l program can be started from the command line or it can be started as a service. When running as a service, options are specified in the /etc/sysconfig/ptp4l file. Options required for use both by the service and on the command line should be specified in the /etc/ptp4l.conf file. The /etc/sysconfig/ptp4l file includes the -f /etc/ptp4l.conf command line option, which causes the ptp4l program to read the /etc/ptp4l.conf file and process the options it contains. The use of the /etc/ptp4l.conf is explained in Section 20.4, “Specifying a Configuration File”. More information on the different ptp4l options and the configuration file settings can be found in the ptp4l(8) man page.

Starting ptp4l as a Service

To start ptp4l as a service, issue the following command as root: 

~]# systemctl start ptp4l

For more information on managing system services in Red Hat Enterprise Linux 7, see Chapter 10, Managing Services with systemd.

Using ptp4l From The Command Line

The ptp4l program tries to use hardware time stamping by default. To use ptp4l with hardware time stamping capable drivers and NICs, you must provide the network interface to use with the -i option. Enter the following command as root: 

~]# ptp4l -i eth3 -m

Where eth3 is the interface you want to configure. Below is example output from ptp4l when the PTP clock on the NIC is synchronized to a master: 

~]# ptp4l -i eth3 -m
selected eth3 as PTP clock
port 1: INITIALIZING to LISTENING on INITIALIZE
port 0: INITIALIZING to LISTENING on INITIALIZE
port 1: new foreign master 00a069.fffe.0b552d-1
selected best master clock 00a069.fffe.0b552d
port 1: LISTENING to UNCALIBRATED on RS_SLAVE
master offset -23947 s0 freq +0 path delay    11350
master offset -28867 s0 freq +0 path delay    11236
master offset -32801 s0 freq +0 path delay    10841
master offset -37203 s1 freq +0 path delay    10583
master offset -7275 s2 freq -30575 path delay  10583
port 1: UNCALIBRATED to SLAVE on MASTER_CLOCK_SELECTED
master offset -4552 s2 freq -30035 path delay  10385

The master offset value is the measured offset from the master in nanoseconds. The s0, s1, s2 strings indicate the different clock servo states: s0 is unlocked, s1 is clock step and s2 is locked. Once the servo is in the locked state (s2), the clock will not be stepped (only slowly adjusted) unless the pi_offset_const option is set to a positive value in the configuration file (described in the ptp4l(8) man page). The adj value is the frequency adjustment of the clock in parts per billion (ppb). The path delay value is 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 eth3 interface (based on the example above.) INITIALIZING, LISTENING, UNCALIBRATED and SLAVE are some of possible port states which change on the INITIALIZE, RS_SLAVE, MASTER_CLOCK_SELECTED events. In the last state change message, the port state changed from UNCALIBRATED to SLAVE indicating successful synchronization with a PTP master clock.

Logging Messages From ptp4l

By default, messages are sent to /var/log/messages. However, specifying the -m option enables logging to standard output which can be useful for debugging purposes.

To enable software time stamping, the -S option needs to be used as follows: 

~]# ptp4l -i eth3 -m -S

20.2.3.1. Selecting a Delay Measurement Mechanism

There are two different delay measurement mechanisms and they can be selected by means of an option added to the ptp4l command as follows:

-P

The -P selects the peer-to-peer (P2P) delay measurement mechanism.

The P2P mechanism is preferred as it reacts to changes in the network topology faster, and may be more accurate in measuring the delay, than other mechanisms. The P2P mechanism can only be used in topologies where each port exchanges PTP messages with at most one other P2P port. It must be supported and used by all hardware, including transparent clocks, on the communication path.

-E

The -E selects the end-to-end (E2E) delay measurement mechanism. This is the default.

The E2E mechanism is also referred to as the delay "request-response" mechanism.

-A

The -A enables automatic selection of the delay measurement mechanism.

The automatic option starts ptp4l in E2E mode. It will change to P2P mode if a peer delay request is received.

Note

All clocks on a single PTP communication path must use the same mechanism to measure the delay. Warnings will be printed in the following circumstances:

  • When a peer delay request is received on a port using the E2E mechanism.
  • When a E2E delay request is received on a port using the P2P mechanism.

20.3. Using PTP with Multiple Interfaces

When using PTP with multiple interfaces in different networks, it is necessary to change the reverse path forwarding mode to loose mode. Red Hat Enterprise Linux 7 defaults to using Strict Reverse Path Forwarding following the Strict Reverse Path recommendation from RFC 3704, Ingress Filtering for Multihomed Networks. See the Reverse Path Forwarding section in the Red Hat Enterprise Linux 7 Security Guide for more details.

The sysctl utility is used to read and write values to tunables in the kernel. Changes to a running system can be made using sysctl commands directly on the command line and permanent changes can be made by adding lines to the /etc/sysctl.conf file.

  • To change to loose mode filtering globally, enter the following commands as root: 

    ~]# sysctl -w net.ipv4.conf.default.rp_filter=2
~]# sysctl -w net.ipv4.conf.all.rp_filter=2

  • To change the reverse path filtering mode per network interface, use the net.ipv4.interface.rp_filter command on all PTP interfaces. For example, for an interface with device name em1: 

    ~]# sysctl -w net.ipv4.conf.em1.rp_filter=2

To make these settings persistent across reboots, modify the /etc/sysctl.conf file. You can change the mode for all interfaces, or for a particular interface.

To change the mode for all interfaces, open the /etc/sysctl.conf file with an editor running as the root user and add a line as follows: 

net.ipv4.conf.all.rp_filter=2

To change only certain interfaces, add multiple lines in the following format: 

net.ipv4.conf.interface.rp_filter=2
Note

When using the settings for all and particular interfaces as well, maximum value from conf/{all,interface}/rp_filter is used when doing source validation on each interface.

You can also change the mode by using the default setting, which means that it applies only to the newly created interfaces.

For more information on using the all, default, or a specific device settings in the sysctl parameters, see the Red Hat Knowledgebase article What is the difference between "all", "default" and a specific device in a sysctl parameter?.

Note that you might experience issues of two types due to the timing of the sysctl service run during the boot process:

  1. Drivers are loaded before the sysctl service runs.

    In this case, affected network interfaces use the mode preset from the kernel, and sysctl defaults are ignored.

    For solution of this problem, see the Red Hat Knowledgebase article What is the difference between "all", "default" and a specific device in a sysctl parameter?.

  2. Drivers are loaded or reloaded after the sysctl service runs.

    In this case, it is possible that some sysctl.conf parameters are not used after reboot. These settings may not be available or they may return to defaults.

    For solution of this problem, see the Red Hat Knowledgebase article Some sysctl.conf parameters are not used after reboot, manually adjusting the settings works as expected.

20.4. Specifying a Configuration File

The command line options and other options, which cannot be set on the command line, can be set in an optional configuration file.

No configuration file is read by default, so it needs to be specified at runtime with the -f option. For example: 

~]# ptp4l -f /etc/ptp4l.conf

A configuration file equivalent to the -i eth3 -m -S options shown above would look as follows: 

~]# cat /etc/ptp4l.conf
[global]
verbose        1
time_stamping     software
[eth3]

20.5. Using the PTP Management Client

The PTP management client, pmc, can be used to obtain additional information from ptp4l as follows: 

~]# pmc -u -b 0 'GET CURRENT_DATA_SET'
sending: GET CURRENT_DATA_SET
    90e2ba.fffe.20c7f8-0 seq 0 RESPONSE MANAGMENT CURRENT_DATA_SET
        stepsRemoved    1
        offsetFromMaster -142.0
        meanPathDelay   9310.0
~]# pmc -u -b 0 'GET TIME_STATUS_NP'
sending: GET TIME_STATUS_NP
    90e2ba.fffe.20c7f8-0 seq 0 RESPONSE MANAGMENT TIME_STATUS_NP
        master_offset       310
        ingress_time        1361545089345029441
        cumulativeScaledRateOffset  +1.000000000
        scaledLastGmPhaseChange  0
        gmTimeBaseIndicator    0
        lastGmPhaseChange     0x0000'0000000000000000.0000
        gmPresent         true
        gmIdentity         00a069.fffe.0b552d

Setting the -b option to zero limits the boundary to the locally running ptp4l instance. A larger boundary value will retrieve the information also from PTP nodes further from the local clock. The retrievable information includes:

  • stepsRemoved is the number of communication paths to the grandmaster clock.
  • offsetFromMaster and master_offset is the last measured offset of the clock from the master in nanoseconds.
  • meanPathDelay is the estimated delay of the synchronization messages sent from the master in nanoseconds.
  • if gmPresent is true, the PTP clock is synchronized to a master, the local clock is not the grandmaster clock.
  • gmIdentity is the grandmaster’s identity.

For a full list of pmc commands, type the following as root: 

~]# pmc help

Additional information is available in the pmc(8) man page.

20.6. Synchronizing the Clocks

The phc2sys program is used to synchronize the system clock to the PTP hardware clock (PHC) on the NIC. The phc2sys service is configured in the /etc/sysconfig/phc2sys configuration file. The default setting in the /etc/sysconfig/phc2sys file is as follows: 

OPTIONS="-a -r"

The -a option causes phc2sys to read the clocks to be synchronized from the ptp4l application. It will follow changes in the PTP port states, adjusting the synchronization between the NIC hardware clocks accordingly. The system clock is not synchronized, unless the -r option is also specified. If you want the system clock to be eligible to become a time source, specify the -r option twice.

After making changes to /etc/sysconfig/phc2sys, restart the phc2sys service from the command line by issuing a command as root: 

~]# systemctl restart phc2sys

Under normal circumstances, use systemctl commands to start, stop, and restart the phc2sys service.

When you do not want to start phc2sys as a service, you can start it from the command line. For example, enter the following command as root: 

~]# phc2sys -a -r

The -a option causes phc2sys to read the clocks to be synchronized from the ptp4l application. If you want the system clock to be eligible to become a time source, specify the -r option twice.

Alternately, use the -s option to synchronize the system clock to a specific interface’s PTP hardware clock. For example: 

~]# phc2sys -s eth3 -w

The -w option waits for the running ptp4l application to synchronize the PTP clock and then retrieves the TAI to UTC offset from ptp4l.

Normally, PTP operates in the International Atomic Time (TAI) timescale, while the system clock is kept in Coordinated Universal Time (UTC). The current offset between the TAI and UTC timescales is 36 seconds. The offset changes when leap seconds are inserted or deleted, which typically happens every few years. The -O option needs to be used to set this offset manually when the -w is not used, as follows: 

~]# phc2sys -s eth3 -O -36

Once the phc2sys servo is in a locked state, the clock will not be stepped, unless the -S option is used. This means that the phc2sys program should be started after the ptp4l program has synchronized the PTP hardware clock. However, with -w, it is not necessary to start phc2sys after ptp4l as it will wait for it to synchronize the clock.

The phc2sys program can also be started as a service by running: 

~]# systemctl start phc2sys

When running as a service, options are specified in the /etc/sysconfig/phc2sys file. More information on the different phc2sys options can be found in the phc2sys(8) man page.

Note that the examples in this section assume the command is run on a slave system or slave port.

20.7. Verifying Time Synchronization

When PTP time synchronization is working correctly, new messages with offsets and frequency adjustments are printed periodically to the ptp4l and phc2sys outputs if hardware time stamping is used. The output values converge shortly. You can see these messages in the /var/log/messages file.

The following examples of the ptp4l and the phc2sys output contain:

  • offset (in nanoseconds)
  • frequency offset (in parts per billion (ppb))
  • path delay (in nanoseconds)

Example of the ptp4l output: 

ptp4l[352.359]: 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.fffe.0b552d-1
ptp4l[357.214]: selected best master clock 00a069.fffe.0b552d
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 -29492 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 -29436 path delay   8972
ptp4l[364.223]: master offset    266 s2 freq -29900 path delay   9153
ptp4l[365.223]: master offset    430 s2 freq -29656 path delay   9153
ptp4l[366.223]: master offset    615 s2 freq -29342 path delay   9169
ptp4l[367.222]: master offset    -191 s2 freq -29964 path delay   9169
ptp4l[368.223]: master offset    466 s2 freq -29364 path delay   9170
ptp4l[369.235]: master offset     24 s2 freq -29666 path delay   9196
ptp4l[370.235]: master offset    -375 s2 freq -30058 path delay   9238
ptp4l[371.235]: master offset    285 s2 freq -29511 path delay   9199
ptp4l[372.235]: master offset    -78 s2 freq -29788 path delay   9204

Example of the phc2sys output: 

phc2sys[526.527]: Waiting for ptp4l...
phc2sys[527.528]: Waiting for ptp4l...
phc2sys[528.528]: phc offset   55341 s0 freq   +0 delay  2729
phc2sys[529.528]: phc offset   54658 s1 freq -37690 delay  2725
phc2sys[530.528]: phc offset    888 s2 freq -36802 delay  2756
phc2sys[531.528]: phc offset   1156 s2 freq -36268 delay  2766
phc2sys[532.528]: phc offset    411 s2 freq -36666 delay  2738
phc2sys[533.528]: phc offset    -73 s2 freq -37026 delay  2764
phc2sys[534.528]: phc offset    39 s2 freq -36936 delay  2746
phc2sys[535.529]: phc offset    95 s2 freq -36869 delay  2733
phc2sys[536.529]: phc offset   -359 s2 freq -37294 delay  2738
phc2sys[537.529]: phc offset   -257 s2 freq -37300 delay  2753
phc2sys[538.529]: phc offset    119 s2 freq -37001 delay  2745
phc2sys[539.529]: phc offset    288 s2 freq -36796 delay  2766
phc2sys[540.529]: phc offset   -149 s2 freq -37147 delay  2760
phc2sys[541.529]: phc offset   -352 s2 freq -37395 delay  2771
phc2sys[542.529]: phc offset    166 s2 freq -36982 delay  2748
phc2sys[543.529]: phc offset    50 s2 freq -37048 delay  2756
phc2sys[544.530]: phc offset    -31 s2 freq -37114 delay  2748
phc2sys[545.530]: phc offset   -333 s2 freq -37426 delay  2747
phc2sys[546.530]: phc offset    194 s2 freq -36999 delay  2749

To reduce the ptp4l output and print only the values, use the summary_interval directive. The summary_interval directive is specified as 2 to the power of n in seconds. For example, to reduce the output to every 1024 seconds, add the following line to the /etc/ptp4l.conf file: 

summary_interval 10

An example of the ptp4l output, with summary_interval set to 6: 

ptp4l: [615.253] selected /dev/ptp0 as PTP clock
ptp4l: [615.255] port 1: INITIALIZING to LISTENING on INITIALIZE
ptp4l: [615.255] port 0: INITIALIZING to LISTENING on INITIALIZE
ptp4l: [615.564] port 1: new foreign master 00a069.fffe.0b552d-1
ptp4l: [619.574] selected best master clock 00a069.fffe.0b552d
ptp4l: [619.574] port 1: LISTENING to UNCALIBRATED on RS_SLAVE
ptp4l: [623.573] port 1: UNCALIBRATED to SLAVE on MASTER_CLOCK_SELECTED
ptp4l: [684.649] rms 669 max 3691 freq -29383 ± 3735 delay 9232 ± 122
ptp4l: [748.724] rms 253 max 588 freq -29787 ± 221 delay 9219 ± 158
ptp4l: [812.793] rms 287 max 673 freq -29802 ± 248 delay 9211 ± 183
ptp4l: [876.853] rms 226 max 534 freq -29795 ± 197 delay 9221 ± 138
ptp4l: [940.925] rms 250 max 562 freq -29801 ± 218 delay 9199 ± 148
ptp4l: [1004.988] rms 226 max 525 freq -29802 ± 196 delay 9228 ± 143
ptp4l: [1069.065] rms 300 max 646 freq -29802 ± 259 delay 9214 ± 176
ptp4l: [1133.125] rms 226 max 505 freq -29792 ± 197 delay 9225 ± 159
ptp4l: [1197.185] rms 244 max 688 freq -29790 ± 211 delay 9201 ± 162

By default, summary_interval is set to 0, so messages are printed once per second, which is the maximum frequency. The messages are logged at the LOG_INFO level. To disable messages, use the -l option to set the maximum log level to 5 or lower: 

~]# phc2sys -l 5

You can use the -u option to reduce the phc2sys output: 

~]# phc2sys -u summary-updates

Where summary-updates is the number of clock updates to include in summary statistics. An example follows: 

~]# phc2sys -s eth3 -w -m -u 60
phc2sys[700.948]: rms 1837 max 10123 freq -36474 ± 4752 delay 2752 ± 16
phc2sys[760.954]: rms 194 max 457 freq -37084 ± 174 delay 2753 ± 12
phc2sys[820.963]: rms 211 max 487 freq -37085 ± 185 delay 2750 ± 19
phc2sys[880.968]: rms 183 max 440 freq -37102 ± 164 delay 2734 ± 91
phc2sys[940.973]: rms 244 max 584 freq -37095 ± 216 delay 2748 ± 16
phc2sys[1000.979]: rms 220 max 573 freq -36666 ± 182 delay 2747 ± 43
phc2sys[1060.984]: rms 266 max 675 freq -36759 ± 234 delay 2753 ± 17

When used with these options, the interval for updating the statistics is set to 60 seconds (-u), phc2sys waits until ptp4l is in synchronized state (-w), and messages are printed to the standard output (-m). For further details about the phc2sys options, see the phc2sys(5) man page.

The output includes:

  • offset root mean square (rms)
  • maximum absolute offset (max)
  • frequency offset (freq): its mean, and standard deviation
  • path delay (delay): its mean, and standard deviation

20.8. Serving PTP Time with NTP

The ntpd daemon can be configured to distribute the time from the system clock synchronized by ptp4l or phc2sys by using the LOCAL reference clock driver. To prevent ntpd from adjusting the system clock, the ntp.conf file must not specify any NTP servers. The following is a minimal example of ntp.conf: 

~]# cat /etc/ntp.conf
server  127.127.1.0
fudge  127.127.1.0 stratum 0
Note

When the DHCP client program, dhclient, receives a list of NTP servers from the DHCP server, it adds them to ntp.conf and restarts the service. To disable that feature, add PEERNTP=no to /etc/sysconfig/network.

20.9. Serving NTP Time with PTP

NTP to PTP synchronization in the opposite direction is also possible. When ntpd is used to synchronize the system clock, ptp4l can be configured with the priority1 option (or other clock options included in the best master clock algorithm) to be the grandmaster clock and distribute the time from the system clock via PTP: 

~]# cat /etc/ptp4l.conf
[global]
priority1 127
[eth3]
# ptp4l -f /etc/ptp4l.conf

With hardware time stamping, phc2sys needs to be used to synchronize the PTP hardware clock to the system clock. If running phc2sys as a service, edit the /etc/sysconfig/phc2sys configuration file. The default setting in the /etc/sysconfig/phc2sys file is as follows: 

OPTIONS="-a -r"

As root, edit that line as follows: 

~]# vi /etc/sysconfig/phc2sys
OPTIONS="-a -r -r"

The -r option is used twice here to allow synchronization of the PTP hardware clock on the NIC from the system clock. Restart the phc2sys service for the changes to take effect: 

~]# systemctl restart phc2sys

To prevent quick changes in the PTP clock’s frequency, the synchronization to the system clock can be loosened by using smaller P (proportional) and I (integral) constants for the PI servo: 

~]# phc2sys -a -r -r -P 0.01 -I 0.0001

20.10. Synchronize to PTP or NTP Time Using timemaster

When there are multiple PTP domains available on the network, or fallback to NTP is needed, the timemaster program can be used to synchronize the system clock to all available time sources. The PTP time is provided by phc2sys and ptp4l via shared memory driver (SHM reference clocks to chronyd or ntpd (depending on the NTP daemon that has been configured on the system). The NTP daemon can then compare all time sources, both PTP and NTP, and use the best sources to synchronize the system clock.

On start, timemaster reads a configuration file that specifies the NTP and PTP time sources, checks which network interfaces have their own or share a PTP hardware clock (PHC), generates configuration files for ptp4l and chronyd or ntpd, and starts the ptp4l, phc2sys, and chronyd or ntpd processes as needed. It will remove the generated configuration files on exit. It writes configuration files for chronyd, ntpd, and ptp4l to /var/run/timemaster/.

20.10.1. Starting timemaster as a Service

To start timemaster as a service, issue the following command as root: 

~]# systemctl start timemaster

This will read the options in /etc/timemaster.conf. For more information on managing system services in Red Hat Enterprise Linux 7, see Chapter 10, Managing Services with systemd.

20.10.2. Understanding the timemaster Configuration File

Red Hat Enterprise Linux provides a default /etc/timemaster.conf file with a number of sections containing default options. The section headings are enclosed in brackets.

To view the default configuration, issue a command as follows: 

~]$ less /etc/timemaster.conf
# Configuration file for timemaster

#[ntp_server ntp-server.local]
#minpoll 4
#maxpoll 4

#[ptp_domain 0]
#interfaces eth0

[timemaster]
ntp_program chronyd

[chrony.conf]
include /etc/chrony.conf

[ntp.conf]
includefile /etc/ntp.conf

[ptp4l.conf]

[chronyd]
path /usr/sbin/chronyd
options -u chrony

[ntpd]
path /usr/sbin/ntpd
options -u ntp:ntp -g

[phc2sys]
path /usr/sbin/phc2sys

[ptp4l]
path /usr/sbin/ptp4l

Notice the section named as follows: 

[ntp_server address]

This is an example of an NTP server section, "ntp-server.local" is an example of a host name for an NTP server on the local LAN. Add more sections as required using a host name or IP address as part of the section name. Note that the short polling values in that example section are not suitable for a public server, see Chapter 19, Configuring NTP Using ntpd for an explanation of suitable minpoll and maxpoll values.

Notice the section named as follows: 

[ptp_domain number]

A "PTP domain" is a group of one or more PTP clocks that synchronize to each other. They may or may not be synchronized to clocks in another domain. Clocks that are configured with the same domain number make up the domain. This includes a PTP grandmaster clock. The domain number in each "PTP domain" section needs to correspond to one of the PTP domains configured on the network.

An instance of ptp4l is started for every interface which has its own PTP clock and hardware time stamping is enabled automatically. Interfaces that support hardware time stamping have a PTP clock (PHC) attached, however it is possible for a group of interfaces on a NIC to share a PHC. A separate ptp4l instance will be started for each group of interfaces sharing the same PHC and for each interface that supports only software time stamping. All ptp4l instances are configured to run as a slave. If an interface with hardware time stamping is specified in more than one PTP domain, then only the first ptp4l instance created will have hardware time stamping enabled.

Notice the section named as follows: 

[timemaster]

The default timemaster configuration includes the system ntpd and chrony configuration (/etc/ntp.conf or /etc/chronyd.conf) in order to include the configuration of access restrictions and authentication keys. That means any NTP servers specified there will be used with timemaster too.

The section headings are as follows:

  • [ntp_server ntp-server.local] — Specify polling intervals for this server. Create additional sections as required. Include the host name or IP address in the section heading.
  • [ptp_domain 0] — Specify interfaces that have PTP clocks configured for this domain. Create additional sections with, the appropriate domain number, as required.
  • [timemaster] — Specify the NTP daemon to be used. Possible values are chronyd and ntpd.
  • [chrony.conf] — Specify any additional settings to be copied to the configuration file generated for chronyd.
  • [ntp.conf] — Specify any additional settings to be copied to the configuration file generated for ntpd.
  • [ptp4l.conf] — Specify options to be copied to the configuration file generated for ptp4l.
  • [chronyd] — Specify any additional settings to be passed on the command line to chronyd.
  • [ntpd] — Specify any additional settings to be passed on the command line to ntpd.
  • [phc2sys] — Specify any additional settings to be passed on the command line to phc2sys.
  • [ptp4l] — Specify any additional settings to be passed on the command line to all instances of ptp4l.

The section headings and there contents are explained in detail in the timemaster(8) manual page.

20.10.3. Configuring timemaster Options

Editing the timemaster Configuration File

  1. To change the default configuration, open the /etc/timemaster.conf file for editing as root: 

    ~]# vi /etc/timemaster.conf
  2. For each NTP server you want to control using timemaster, create [ntp_server address] sections. Note that the short polling values in the example section are not suitable for a public server, see Chapter 19, Configuring NTP Using ntpd for an explanation of suitable minpoll and maxpoll values.

  3. To add interfaces that should be used in a domain, edit the #[ptp_domain 0] section and add the interfaces. Create additional domains as required. For example: 

    [ptp_domain 0]
    interfaces eth0

    [ptp_domain 1]
    interfaces eth1
  4. If required to use ntpd as the NTP daemon on this system, change the default entry in the [timemaster] section from chronyd to ntpd. See Chapter 18, Configuring NTP Using the chrony Suite for information on the differences between ntpd and chronyd.
  5. If using chronyd as the NTP server on this system, add any additional options below the default include /etc/chrony.conf entry in the [chrony.conf] section. Edit the default include entry if the path to /etc/chrony.conf is known to have changed.
  6. If using ntpd as the NTP server on this system, add any additional options below the default include /etc/ntp.conf entry in the [ntp.conf] section. Edit the default include entry if the path to /etc/ntp.conf is known to have changed.
  7. In the [ptp4l.conf] section, add any options to be copied to the configuration file generated for ptp4l. This chapter documents common options and more information is available in the ptp4l(8) manual page.
  8. In the [chronyd] section, add any command line options to be passed to chronyd when called by timemaster. See Chapter 18, Configuring NTP Using the chrony Suite for information on using chronyd.
  9. In the [ntpd] section, add any command line options to be passed to ntpd when called by timemaster. See Chapter 19, Configuring NTP Using ntpd for information on using ntpd.
  10. In the [phc2sys] section, add any command line options to be passed to phc2sys when called by timemaster. This chapter documents common options and more information is available in the phy2sys(8) manual page.
  11. In the [ptp4l] section, add any command line options to be passed to ptp4l when called by timemaster. This chapter documents common options and more information is available in the ptp4l(8) manual page.

  12. Save the configuration file and restart timemaster by issuing the following command as root: 

    ~]# systemctl restart timemaster

20.11. Improving Accuracy

Previously, test results indicated that disabling the tickless kernel capability could significantly improve the stability of the system clock, and thus improve the PTP synchronization accuracy (at the cost of increased power consumption). The kernel tickless mode can be disabled by adding nohz=off to the kernel boot option parameters. However, recent improvements applied to kernel-3.10.0-197.el7 have greatly improved the stability of the system clock and the difference in stability of the clock with and without nohz=off should be much smaller now for most users.

The ptp4l and phc2sys applications can be configured to use a new adaptive servo. The advantage over the PI servo is that it does not require configuration of the PI constants to perform well. To make use of this for ptp4l, add the following line to the /etc/ptp4l.conf file: 

clock_servo linreg

After making changes to /etc/ptp4l.conf, restart the ptp4l service from the command line by issuing the following command as root: 

~]# systemctl restart ptp4l

To make use of this for phc2sys, add the following line to the /etc/sysconfig/phc2sys file: 

-E linreg

After making changes to /etc/sysconfig/phc2sys, restart the phc2sys service from the command line by issuing the following command as root: 

~]# systemctl restart phc2sys

20.12. Additional Resources

The following sources of information provide additional resources regarding PTP and the ptp4l tools.

20.12.1. Installed Documentation

  • ptp4l(8) man page — Describes ptp4l options including the format of the configuration file.
  • pmc(8) man page — Describes the PTP management client and its command options.
  • phc2sys(8) man page — Describes a tool for synchronizing the system clock to a PTP hardware clock (PHC).
  • timemaster(8) man page — Describes a program that uses ptp4l and phc2sys to synchronize the system clock using chronyd or ntpd.

20.12.2. Useful Websites

http://www.nist.gov/el/isd/ieee/ieee1588.cfm
The IEEE 1588 Standard.