You are viewing the documentation for a prerelease version. View Latest

Configuring PTP Using ptp4l

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 Fedora 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).

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.

Şekil 1. PTP grandmaster, boundary, and slave Clocks

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.

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.

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 as follows:

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

Where em3 is the interface you want to check.

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

Installing PTP

The kernel in Fedora 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:

~]# dnf 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 Serving PTP Time with NTP.

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 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

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 em3 -m

Where em3 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 em3 -m
selected em3 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 em3 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.

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

~]# systemctl start ptp4l

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

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 em3 -m -S

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.

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.

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 em3 -m -S options shown above would look as follows:

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

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.

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 em3 -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 35 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 em3 -O -35

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.

Verifying Time Synchronization

When PTP time synchronization is working properly, new messages with offsets and frequency adjustments will be printed periodically to the ptp4l and phc2sys (if hardware time stamping is used) outputs. These values will eventually converge after a short period of time. These messages can be seen in /var/log/messages file. An example of the output follows:

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

An example of the phc2sys output follows:

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

For ptp4l there is also a directive, summary_interval, to reduce the output and print only statistics, as normally it will print a message every second or so. 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 6, follows:

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

To reduce the output from the phc2sys, it can be called it with the -u option as follows:

~]# phc2sys -u summary-updates

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

~]# phc2sys -s em3 -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

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

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.

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
[em3]
# 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

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

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.

Understanding the timemaster Configuration File

Fedora 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 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.

Configuring timemaster Options

Editing the timemaster Configuration File

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

~]# vi /etc/timemaster.conf

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 Configuring NTP Using ntpd for an explanation of suitable minpoll and maxpoll values.
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

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 Configuring NTP Using the chrony Suite for information on the differences between ntpd and chronyd.
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.
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.
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.
In the [chronyd] section, add any command line options to be passed to chronyd when called by timemaster. See Configuring NTP Using the chrony Suite for information on using chronyd.
In the [ntpd] section, add any command line options to be passed to ntpd when called by timemaster. See Configuring NTP Using ntpd for information on using ntpd.
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.
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.
Save the configuration file and restart timemaster by issuing the following command as root:

~]# systemctl restart timemaster

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.fc21 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

Additional Resources

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

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.

Useful Websites

http://linuxptp.sourceforge.net/: The Linux PTP project.
https://www.nist.gov/el/isd/ieee/ieee1588.cfm: The IEEE 1588 Standard.

Want to help? Learn how to contribute to Fedora Docs ›