[system-administrators-guide/21] Synchronize to PTP or NTP Time Using timemaster

stephenw stephenw at fedoraproject.org
Thu Jan 15 21:26:41 UTC 2015 

commit 65c8aeb722ea1e74278dcacc26f3898c4c9c4ce4
Author: Stephen Wadeley <swadeley at redhat.com>
Date:   Tue Dec 16 21:55:31 2014 +0100

    Synchronize to PTP or NTP Time Using timemaster

 en-US/Configuring_PTP_Using_ptp4l.xml |  229 ++++++++++++++++++++++++++++++++-
 1 files changed, 227 insertions(+), 2 deletions(-)
---
diff --git a/en-US/Configuring_PTP_Using_ptp4l.xml b/en-US/Configuring_PTP_Using_ptp4l.xml
index ba5e354..75e812e 100644
--- a/en-US/Configuring_PTP_Using_ptp4l.xml
+++ b/en-US/Configuring_PTP_Using_ptp4l.xml
@@ -466,11 +466,230 @@ priority1 127
 <para>
 With hardware time stamping, <application>phc2sys</application> needs to be used to synchronize the <systemitem class="protocol">PTP</systemitem> hardware clock to the system clock:
 <screen>~]#&nbsp;<command>phc2sys -c <replaceable>em3</replaceable> -s CLOCK_REALTIME -w</command></screen>
+<section id="sec-Synchronize_to_PTP_or_NTP_Time_Using_timemaster">
+<title>Synchronize to PTP or NTP Time Using timemaster</title>
+<para>
+When there are multiple <systemitem class="protocol">PTP</systemitem> domains available on the network, or fallback to <systemitem class="protocol">NTP</systemitem> is needed, the <application>timemaster</application> program can be used to synchronize the system clock to all available time sources. The <systemitem class="protocol">PTP</systemitem> time is provided by <application>phc2sys</application> and <application>ptp4l</application> via <firstterm>shared memory driver</firstterm> (<acronym>SHM</acronym> reference clocks to <systemitem class="daemon">chronyd</systemitem> or <systemitem class="daemon">ntpd</systemitem> (depending on the <systemitem class="protocol">NTP</systemitem> daemon that has been configured on the system). The <systemitem class="protocol">NTP</systemitem> daemon can then compare all time sources, both <systemitem class="protocol">PTP</systemitem> and <systemitem class="protocol">NTP</systemitem>, and use the best sources to synchronize the system c
 lock.</para>
+ <para>
+ On start, <application>timemaster</application> reads a configuration file that specifies the <systemitem class="protocol">NTP</systemitem> and <systemitem class="protocol">PTP</systemitem> time sources, checks which network interfaces have their own or share a <systemitem class="protocol">PTP</systemitem> hardware clock (PHC), generates configuration files for <application>ptp4l</application> and <systemitem class="daemon">chronyd</systemitem> or <systemitem class="daemon">ntpd</systemitem>, and starts the <application>ptp4l</application>, <application>phc2sys</application>, and <systemitem class="daemon">chronyd</systemitem> or <systemitem class="daemon">ntpd</systemitem> processes as needed. It will remove the generated configuration files on exit. It writes configuration files for <systemitem class="daemon">chronyd</systemitem>, <systemitem class="daemon">ntpd</systemitem>, and <application>ptp4l</application> to <filename class="directory">/var/run/timemaster/</filenam
 e>.
+ </para>
+
+ <section id="sec-Starting_timemaster_as_a_Service">
+ <title>Starting timemaster as a Service</title>
+
+<para>
+To start <application>timemaster</application> as a service, issue the following command as <systemitem class="username">root</systemitem>:
+<screen>~]#&nbsp;<command>systemctl start timemaster</command></screen>
+This will read the options in <filename> /etc/timemaster.conf</filename>.
+<!--For more information on managing system services in &MAJOROSVER;, see <xref linkend="chap-Managing_Services_with_systemd" />.-->
+</para>
+
+</section>
+
+<section id="sec-Understanding_the_timemaster_Configuration_File">
+<title>Understanding the timemaster Configuration File</title>
+
+<para>
+   &MAJOROS; provides a default <filename>/etc/timemaster.conf</filename> file with a number of sections containing default options. The section headings are enclosed in brackets.</para>
+
+<para>
+  To view the default configuration, issue a command as follows:
+<screen>~]$ <command>less /etc/timemaster.conf</command>
+# 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</screen>
+</para>
+
+<para>
+Notice the section named as follows:
+<synopsis>[ntp_server <replaceable>address</replaceable>]</synopsis>
+This is an example of an <systemitem class="protocol">NTP</systemitem> server section, <quote>ntp-server.local</quote> is an example of a host name for an <systemitem class="protocol">NTP</systemitem> server on the local LAN. Add more sections as required using a host name or <systemitem class="protocol">IP</systemitem> 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 <xref linkend="ch-Configuring_NTP_Using_ntpd" /> for an explanation of suitable <option>minpoll</option> and <option>maxpoll</option> values.
+</para>
+
+<para>
+Notice the section named as follows:
+ <synopsis>[ptp_domain <replaceable>number</replaceable>]</synopsis>
+
+ A <quote>PTP domain</quote> is a group of one or more <systemitem class="protocol">PTP</systemitem> 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 <systemitem class="protocol">PTP</systemitem> grandmaster clock. The domain number in each <quote>PTP domain</quote> section needs to correspond to one of the <systemitem class="protocol">PTP</systemitem> domains configured on the network.</para>
+ <para>
+ An instance of <application>ptp4l</application> is started for every interface which has its own <systemitem class="protocol">PTP</systemitem> clock and hardware time stamping is enabled automatically. Interfaces that support hardware time stamping have a <systemitem class="protocol">PTP</systemitem> clock (PHC) attached, however it is possible for a group of interfaces on a NIC to share a PHC. A separate <application>ptp4l</application> instance will be started for each group of interfaces sharing the same PHC and for each interface that supports only software time stamping. All <application>ptp4l</application> instances are configured to run as a slave. If an interface with hardware time stamping is specified in more than one <systemitem class="protocol">PTP</systemitem> domain, then only the first <application>ptp4l</application> instance created will have hardware time stamping enabled.
+ </para>
+
+ <para>
+ Notice the section named as follows:
+ <synopsis>[timemaster]</synopsis>
+   The default <application>timemaster</application> configuration includes the system <systemitem class="daemon">ntpd</systemitem> and chrony configuration (<filename>/etc/ntp.conf</filename> or <filename>/etc/chronyd.conf</filename>) in order to include the configuration of access restrictions and authentication keys. That means any <systemitem class="protocol">NTP</systemitem> servers specified there will be used with <application>timemaster</application> too.
+ </para>
+
+<para>
+  The section headings are as follows:
+</para>
+ <itemizedlist>
+   <listitem>
+   <para>
+    <option>[ntp_server ntp-server.local]</option> — Specify polling intervals for this server. Create additional sections as required. Include the host name or <systemitem class="protocol">IP</systemitem> address in the section heading.
+    </para>
+   </listitem>
+   <listitem>
+   <para>
+    <option>[ptp_domain 0]</option> — Specify interfaces that have <systemitem class="protocol">PTP</systemitem> clocks configured for this domain. Create additional sections with, the appropriate domain number, as required.
+    </para>
+   </listitem>
+   <listitem>
+   <para>
+    <option>[timemaster]</option> — Specify the <systemitem class="protocol">NTP</systemitem> daemon to be used. Possible values are <systemitem class="daemon">chronyd</systemitem> and <systemitem class="daemon">ntpd</systemitem>.
+    </para>
+   </listitem>
+   <listitem>
+   <para>
+    <option>[chrony.conf]</option> — Specify any additional settings to be copied to the configuration file generated for <systemitem class="daemon">chronyd</systemitem>.
+    </para>
+   </listitem>
+      <listitem>
+      <para>
+    <option>[ntp.conf]</option> — Specify any additional settings to be copied to the configuration file generated for <systemitem class="daemon">ntpd</systemitem>.
+    </para>
+   </listitem>
+      <listitem>
+      <para>
+    <option>[ptp4l.conf]</option> — Specify options to be copied to the configuration file generated for <application>ptp4l</application>.
+    </para>
+   </listitem>
+      <listitem>
+      <para>
+    <option>[chronyd]</option> — Specify any additional settings to be passed on the command line to <systemitem class="daemon">chronyd</systemitem>.
+    </para>
+   </listitem>
+         <listitem>
+         <para>
+    <option>[ntpd]</option> — Specify any additional settings to be passed on the command line to <systemitem class="daemon">ntpd</systemitem>.
+    </para>
+   </listitem>
+         <listitem>
+         <para>
+    <option>[phc2sys]</option> — Specify any additional settings to be passed on the command line to <application>phc2sys</application>.
+    </para>
+   </listitem>
+         <listitem>
+         <para>
+    <option>[ptp4l]</option> — Specify any additional settings to be passed on the command line to all instances of <application>ptp4l</application>.
+    </para>
+   </listitem>
+
+    </itemizedlist>
+    <para>
+      The section headings and there contents are explained in detail in the <filename>timemaster(8)</filename> manual page.
+    </para>
+
+</section>
+
+<section id="sec-Configuring_timemaster_Options">
+<title>Configuring timemaster Options</title>
+
+<procedure id="proc-Editing_the_timemaster_Configuration_File">
+<title>Editing the timemaster Configuration File</title>
+<step>
+ <para>
+  To change the default configuration, open the <filename>/etc/timemaster.conf</filename> file for editing as <systemitem class="username">root</systemitem>:
+<screen>~]# <command>vi /etc/timemaster.conf</command></screen>
+</para>
+</step>
+<step>
+<para>
+  For each <systemitem class="protocol">NTP</systemitem> server you want to control using <application>timemaster</application>, create <computeroutput>[ntp_server <replaceable>address</replaceable>]</computeroutput> sections . Note that the short polling values in the example section are not suitable for a public server, see <xref linkend="ch-Configuring_NTP_Using_ntpd" /> for an explanation of suitable <option>minpoll</option> and <option>maxpoll</option> values.
+  </para>
+</step>
+<step>
+  <para>
+  To add interfaces that should be used in a domain, edit the <computeroutput>#[ptp_domain 0]</computeroutput> section and add the interfaces. Create additional domains as required. For example:
+  <screen>[ptp_domain 0]
+       interfaces eth0
+
+       [ptp_domain 1]
+       interfaces eth1</screen>
+</para>
+</step>
+<step>
+<para>
+If required to use <systemitem class="daemon">ntpd</systemitem> as the <systemitem class="protocol">NTP</systemitem> daemon on this system, change the default entry in the <computeroutput>[timemaster]</computeroutput> section from <systemitem class="daemon">chronyd</systemitem> to <systemitem class="daemon">ntpd</systemitem>. See <xref linkend="ch-Configuring_NTP_Using_the_chrony_Suite" /> for information on the differences between ntpd and chronyd.
+  </para>
+</step>
+<step>
+  <para>
+   If using <systemitem class="daemon">chronyd</systemitem> as the <systemitem class="protocol">NTP</systemitem> server on this system, add any additional options below the default <option>include /etc/chrony.conf</option> entry in the <computeroutput>[chrony.conf]</computeroutput> section. Edit the default <option>include</option> entry if the path to <filename>/etc/chrony.conf</filename> is known to have changed.
+  </para>
+</step>
+<step>
+  <para>
+   If using <systemitem class="daemon">ntpd</systemitem> as the <systemitem class="protocol">NTP</systemitem> server on this system, add any additional options below the default <option>include /etc/ntp.conf</option> entry in the <computeroutput>[ntp.conf]</computeroutput> section. Edit the default <option>include</option> entry if the path to <filename>/etc/ntp.conf</filename> is known to have changed.
+  </para>
+</step>
+<step>
+  <para>
+    In the <computeroutput>[ptp4l.conf]</computeroutput> section, add any options to be copied to the configuration file generated for <application>ptp4l</application>. This chapter documents common options and more information is available in the <filename>ptp4l(8)</filename> manual page.
+  </para>
+</step>
+<step>
+  <para>
+    In the <computeroutput>[chronyd]</computeroutput> section, add any command line options to be passed to <systemitem class="daemon">chronyd</systemitem> when called by <application>timemaster</application>. See <xref linkend="ch-Configuring_NTP_Using_the_chrony_Suite" /> for information on using <systemitem class="daemon">chronyd</systemitem>.
+  </para>
+</step>
+<step>
+  <para>
+    In the <computeroutput>[ntpd]</computeroutput> section, add any command line options to be passed to <systemitem class="daemon">ntpd</systemitem> when called by <application>timemaster</application>. See <xref linkend="ch-Configuring_NTP_Using_ntpd" /> for information on using <systemitem class="daemon">ntpd</systemitem>.
+  </para>
+</step>
+<step>
+  <para>
+    In the <computeroutput>[phc2sys]</computeroutput> section, add any command line options to be passed to <application>phc2sys</application> when called by <application>timemaster</application>. This chapter documents common options and more information is available in the <filename>phy2sys(8)</filename> manual page.
+  </para>
+</step>
+<step>
+  <para>
+    In the <computeroutput>[ptp4l]</computeroutput> section, add any command line options to be passed to <application>ptp4l</application> when called by <application>timemaster</application>. This chapter documents common options and more information is available in the <filename>ptp4l(8)</filename> manual page.
   </para>
+</step>
+<step>
   <para>
-    To prevent quick changes in the <systemitem class="protocol">PTP</systemitem> clock's frequency, the synchronization to the system clock can be loosened by using smaller <option>P</option> (proportional) and <option>I</option> (integral) constants of the PI servo:
-<screen>~]#&nbsp;<command>phc2sys -c <replaceable>em3</replaceable> -s CLOCK_REALTIME -w -P 0.01 -I 0.0001</command></screen>
+    Save the configuration file and restart <application>timemaster</application> by issuing the following command as <systemitem class="username">root</systemitem>:
+<screen>~]# <command>systemctl restart timemaster</command></screen>
+
   </para>
+</step>
+
+</procedure>
+</section>
+
 </section>
 
 <section id="sec-Improving_Accuracy">
@@ -505,6 +724,12 @@ With hardware time stamping, <application>phc2sys</application> needs to be used
 <filename>phc2sys(8)</filename> man page — Describes a tool for synchronizing the system clock to a <systemitem class="protocol">PTP</systemitem> hardware clock (PHC).
       </para>
     </listitem>
+    <listitem>
+      <para>
+<filename>timemaster(8)</filename> man page — Describes a program that uses <application>ptp4l</application> and <application>phc2sys</application> to synchronize the system clock using <systemitem class="daemon">chronyd</systemitem> or <systemitem class="daemon">ntpd</systemitem>.
+</para>
+    </listitem>
+
 
   </itemizedlist>
 </section>

More information about the docs-commits mailing list