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

Procedure 20.1. 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