Merge lp:~paelzer/serverguide/serverguide-chrony-18.04 into lp:serverguide/trunk

[Christian Ehrhardt ]

Update for 18.04 for the time synchronization chapter
- general 18.04 updates (e.g. new output)
- recommended NTP server changed from ntpd to chrony (LP: #1744072)
- minor cleanups while working at the section

[Doug Smythies (dsmythies)]

thanks very much.

review: Approve

[Simon Déziel (sdeziel)]

LGTM with 2 minor nitpicks.

[Doug Smythies (dsmythies)]

@Simon: Thank you very much for your diligence. Since I already pushed this one, I'll make edits and push another revision.

[Simon Déziel (sdeziel)]

Alright, thanks guys.

=== modified file 'serverguide/C/network-auth.xml'
--- serverguide/C/network-auth.xml	2017-11-06 15:28:57 +0000
+++ serverguide/C/network-auth.xml	2018-02-23 10:55:44 +0000
@@ -3977,7 +3977,7 @@
 		<para>The following packages are needed: <emphasis>krb5-user</emphasis>, <emphasis>samba</emphasis>, <emphasis>sssd</emphasis>, and <emphasis>ntp</emphasis>.  Samba needs to be installed, even if the system is not exporting shares. The Kerberos realm and FQDN or IP of the domain controllers are needed for this step.</para>
 		<para>Install these packages now.
 		</para>
-		<screen><command>sudo apt install krb5-user samba sssd ntp</command></screen>
+		<screen><command>sudo apt install krb5-user samba sssd chrony</command></screen>
 		<para>See the next section for the answers to the questions asked by the <emphasis>krb5-user</emphasis> postinstall script.</para>
 	</sect2>
 	<sect2 id="sssd-ad-kerberos" status="review">
@@ -3997,7 +3997,7 @@
 
 		<para>If default_realm is not specified, it may be necessary to log in with <quote>username@domain</quote> instead of <quote>username</quote>.</para>
 
-		<para>The system time on the Active Directory member needs to be consistent with that of the domain controller, or Kerberos authentication may fail.  Ideally, the domain controller server itself will provide the NTP service. Edit <filename>/etc/ntp.conf</filename>:</para>
+        <para>The system time on the Active Directory member needs to be consistent with that of the domain controller, or Kerberos authentication may fail.  Ideally, the domain controller server itself will provide the NTP service. Edit <filename>/etc/chrony/chrony.conf</filename>:</para>
 
 <programlisting>
 server dc.myubuntu.example.com
@@ -4085,8 +4085,8 @@
 
 <sect2 id="sssd-ad-join" status="review">
 	<title>Join the Active Directory</title>
-<para>Now, restart ntp and samba and start sssd.</para>
-<screen><command>sudo systemctl restart ntp.service</command>
+<para>Now, restart chrony and samba and start sssd.</para>
+<screen><command>sudo systemctl restart chrony.service</command>
 <command>sudo systemctl restart smbd.service nmbd.service</command> 
 <command>sudo systemctl start sssd.service</command></screen>
 
 
=== modified file 'serverguide/C/network-config.xml'
--- serverguide/C/network-config.xml	2017-07-02 17:41:08 +0000
+++ serverguide/C/network-config.xml	2018-02-23 10:55:44 +0000
@@ -1055,34 +1055,49 @@
     </sect1>
 
 	<sect1 id="NTP" status="review">
-		<title>Time Synchronisation</title>
+		<title>Time Synchronization</title>
 	<para>
-NTP is a TCP/IP protocol for synchronising time over a network. Basically a client requests the current time from a server, and uses it to set its own clock.  
+NTP is a TCP/IP protocol for synchronizing time over a network. Basically a client requests the current time from a server, and uses it to set its own clock.  
 </para>
 	<para>
 Behind this simple description, there is a lot of complexity - there are tiers of NTP servers, with the tier one NTP servers connected to atomic clocks, and tier two and three servers spreading the load of actually handling requests across the Internet. Also the client software is a lot more complex than you might think - it has to factor out communication delays, and adjust the time in a way that does not upset all the other processes that run on the server. But luckily all that complexity is hidden from you! 
 </para>
 	<para>
-Ubuntu by default uses <emphasis>timedatectl / timesyncd</emphasis> to synchronize time and users can optionally use ntpd to serve network time info.
+        Ubuntu by default uses <emphasis>timedatectl / timesyncd</emphasis> to synchronize time and users can optionally use chrony to <xref linkend="timeservers"/>.
 </para>
 
 <sect2 id="timedate-info" status="review">
 <title>Synchronizing your systems time</title>
 	<para>
-		Starting with Ubuntu 16.04 <emphasis>timedatectl / timesyncd</emphasis> (which are part of systemd) replace most of <emphasis>ntpdate / ntp</emphasis>.
+		Since Ubuntu 16.04 <emphasis>timedatectl / timesyncd</emphasis> (which are part of systemd) replace most of <emphasis>ntpdate / ntp</emphasis>.
 	</para>
 	<para>
-        <application>timesyncd</application> is available by default and replaces not only <application>ntpdate</application>, but also the client portion of <application>ntpd</application>.
+        <application>timesyncd</application> is available by default and replaces not only <application>ntpdate</application>, but also the client portion of <application>chrony</application> (or formerly <application>ntpd</application>).
 		So on top of the one-shot action that <application>ntpdate</application> provided on boot and network activation, now <application>timesyncd</application> by default regularly checks and keeps your local time in sync.
 		It also stores time updates locally, so that after reboots monotonically advances if applicable.
 	</para>
 	<para>
-		If <application>ntpdate / ntp</application> are installed <application>timedatectl</application> steps back to let you keep your old setup.
-		That shall ensure that no two time syncing services are fighting and also to retain any kind of old behaviour/config that you had through an upgrade.
+		If <application>chrony</application> is installed <application>timedatectl</application> steps back to let chrony do the time keeping.
+        That shall ensure that no two time syncing services are fighting.
+        While no more recommended to be used, this still also applies to <application>ntpd</application> being installed to retain any kind of old behavior/config that you had through an upgrade.
 		But it also implies that on an upgrade from a former release ntp/ntpdate might still be installed and therefore renders the new systemd based services disabled.
 	</para>
 	<para>
-		<application>ntpdate</application> is considered deprecated in favour of <application>timedatectl</application> and thereby no more installed by default.
+        <application>ntpdate</application> is considered deprecated in favor of <application>timedatectl</application> (or <application>chrony</application>) and thereby no more installed by default.
+        timesyncd will generally do the right thing keeping your time in sync, and <application>chrony</application> will help with more complex cases.
+        But if you had one of a few known special ntpdate use cases, consider the following:
+        <itemizedlist>
+          <listitem>
+            <para>
+              If you require a one-shot sync use: <command>chronyd -q</command>
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              If you require a one-shot time check, without setting the time use: <command>chronyd -Q</command>
+            </para>
+          </listitem>
+        </itemizedlist>
 	</para>
 
 <sect3 id="timedate-config" status="review">
@@ -1090,16 +1105,20 @@
 	<para>
 		The current status of time and time configuration via <application>timedatectl</application> and <application>timesyncd</application> can be checked with <command>timedatectl status</command>.
 	</para>
-<screen>
+      <screen>
 $ timedatectl status
-      Local time: Mo 2017-06-26 12:16:16 CEST
-  Universal time: Mo 2017-06-26 10:16:16 UTC
-        RTC time: Mo 2017-06-26 10:16:16
-       Time zone: Europe/Berlin (CEST, +0200)
- Network time on: yes
-NTP synchronized: yes
- RTC in local TZ: no
-</screen>
+                       Local time: Fr 2018-02-23 08:47:13 UTC
+                   Universal time: Fr 2018-02-23 08:47:13 UTC
+                         RTC time: Fr 2018-02-23 08:47:13
+                        Time zone: Etc/UTC (UTC, +0000)
+        System clock synchronized: yes
+ systemd-timesyncd.service active: yes
+                  RTC in local TZ: no
+
+If chrony is running it will automatically switch to:
+[...]
+ systemd-timesyncd.service active: no
+      </screen>
 <para>
 Via <application>timedatectl</application> an admin can control the timezone, how the system clock should relate to the hwclock and if permanent synronization should be enabled or not.
 See <command>man timedatectl</command> for more details.
@@ -1108,62 +1127,75 @@
         timesyncd itself is still a normal service, so you can check its status also more in detail via.
 <screen>
 $ systemctl status systemd-timesyncd
-. systemd-timesyncd.service - Network Time Synchronization
+  systemd-timesyncd.service - Network Time Synchronization
    Loaded: loaded (/lib/systemd/system/systemd-timesyncd.service; enabled; vendor preset: enabled)
-  Drop-In: /lib/systemd/system/systemd-timesyncd.service.d
-           |_disable-with-time-daemon.conf
-   Active: active (running) since Mo 2017-06-26 11:12:19 CEST; 30min ago
+   Active: active (running) since Fri 2018-02-23 08:55:46 UTC; 10s ago
      Docs: man:systemd-timesyncd.service(8)
- Main PID: 12379 (systemd-timesyn)
-   Status: "Synchronized to time server [2001:67c:1560:8003::c8]:123 (ntp.ubuntu.com)."
-    Tasks: 2
-   Memory: 424.0K
-      CPU: 12ms
+ Main PID: 3744 (systemd-timesyn)
+   Status: "Synchronized to time server 91.189.89.198:123 (ntp.ubuntu.com)."
+    Tasks: 2 (limit: 4915)
    CGroup: /system.slice/systemd-timesyncd.service
-           |_12379 /lib/systemd/systemd-timesyncd
+           └─3744 /lib/systemd/systemd-timesyncd
 
-Jun 26 11:12:19 lap systemd[1]: Starting Network Time Synchronization...
-Jun 26 11:12:19 lap systemd[1]: Started Network Time Synchronization.
-Jun 26 11:12:19 lap systemd-timesyncd[12379]: Synchronized to time server [2001:67c:1560:8003::c8]:123 (ntp.ubuntu.com).
+Feb 23 08:55:46 bionic-test systemd[1]: Starting Network Time Synchronization...
+Feb 23 08:55:46 bionic-test systemd[1]: Started Network Time Synchronization.
+Feb 23 08:55:46 bionic-test systemd-timesyncd[3744]: Synchronized to time server 91.189.89.198:123 (ntp.ubuntu.com).
 </screen>
 </para>
 <para>
         The nameserver to fetch time for <application>timedatectl</application> and <application>timesyncd</application> from can be specified in <filename>/etc/systemd/timesyncd.conf</filename> and additional config files can be stored in <filename>/etc/systemd/timesyncd.conf.d/</filename>.
         The entries for NTP= and FallbackNTP= are space separated lists.
+        See <command>man timesyncd.conf</command> for more.
 </para>
 </sect3>
 
 </sect2>
 
 <sect2 id="timeservers" status="review">
-   <title>Serving NTP</title>
+   <title>Serve the Network Time Protocol</title>
    <para>
-       If on top of synchronizing your system you also want to serve NTP information you need an ntp server. The most classic and supported one is <application>ntpd</application>, but it is also very old so there also are <application>openntpd</application> and <application>chrony</application> as alternatives available in the archive.
+       If in addition to synchronizing your system you also want to serve NTP information you need an NTP server. There are several options with <application>chrony</application>, <application>ntpd</application> and <application>open-ntp</application>.
+       The recommended solution <application>chrony</application>.
    </para>
 
-<sect3 id="ntpd" status="review">
-   <title>ntpd</title>
+<sect3 id="chrony" status="review">
+   <title>chrony(d)</title>
    <para>
-   The ntp daemon ntpd calculates the drift of your system clock and continuously adjusts it, so there are no large corrections that could
-   lead to inconsistent logs for instance. The cost is a little processing power and memory, but for a modern server this is negligible.
+   The NTP daemon chronyd calculates the drift and offset of your system clock and continuously adjusts it, so there are no large corrections that could
+   lead to inconsistent logs for instance. The cost is a little processing power and memory, but for a modern server this is usually negligible.
    </para>
 </sect3>
 
-<sect3 id="ntp-installation" status="review">
+<sect3 id="chrony-installation" status="review">
    <title>Installation</title>
    <para>
-   To install ntpd, from a terminal prompt enter:
+   To install chrony, from a terminal prompt enter:
    </para>
 <screen>
-<command>sudo apt install ntp</command>
+<command>sudo apt install chrony</command>
 </screen>
+   <para>
+       This will provide two binaries:
+        <itemizedlist>
+          <listitem>
+            <para>
+              chronyd - the actual daemon to sync and serve via the NTP protocol
+            </para>
+          </listitem>
+          <listitem>
+            <para>
+              chronyc - command-line interface for chrony daemon
+            </para>
+          </listitem>
+        </itemizedlist>
+   </para>
 </sect3>
 
 <sect3 id="timeservers-conf" status="review">
-  <title>Configuration</title>
+  <title>Chronyd Configuration</title>
 
   <para>
-  Edit <filename>/etc/ntp.conf</filename> to add/remove server lines.
+      Edit <filename>/etc/chrony/chrony.conf</filename> to add/remove server lines.
   By default these servers are configured:
   </para>
 
@@ -1171,21 +1203,21 @@
 # Use servers from the NTP Pool Project. Approved by Ubuntu Technical Board
 # on 2011-02-08 (LP: #104525). See http://www.pool.ntp.org/join.html for
 # more information.
-server 0.ubuntu.pool.ntp.org
-server 1.ubuntu.pool.ntp.org
-server 2.ubuntu.pool.ntp.org
-server 3.ubuntu.pool.ntp.org
+pool 0.ubuntu.pool.ntp.org iburst
+pool 1.ubuntu.pool.ntp.org iburst
+pool 2.ubuntu.pool.ntp.org iburst
+pool 3.ubuntu.pool.ntp.org iburst
 </programlisting>
 
           <para>
-	  After changing the config file you have to reload the
-          <application>ntpd</application>:
+      See <command>man chrony.conf</command> for more details on the configuration options.
+	  After changing the any of the config file you have to reload <application>chrony</application>:
 	  </para>
 <screen>
-<command>sudo systemctl reload ntp.service</command>
+<command>sudo systemctl restart chrony.service</command>
 </screen>
 <para>
-	   Of the pool number 2.ubuntu.pool.ntp.org as well as ntp.ubuntu.com also support ipv6 if needed.
+	   Of the pool 2.ubuntu.pool.ntp.org as well as ntp.ubuntu.com also support ipv6 if needed.
 	   If one needs to force ipv6 there also is ipv6.ntp.ubuntu.com which is not configured by default.
 </para>
 
@@ -1194,26 +1226,79 @@
 <sect3 id="ntp-status" status="review">
   <title>View status</title>
   <para>
-  Use ntpq to see more info: 
+  Use chronyc to see query the status of the chrony daemon.
+  For example to get an overview of the currently available and selected time sources.
+  </para>
+  <para>
   </para>
 <screen>
-<command># sudo ntpq -p</command>
-<computeroutput>     remote           refid      st t when poll reach   delay   offset  jitter
+<command>chronyc sources</command>
+<computeroutput>
+MS Name/IP address         Stratum Poll Reach LastRx Last sample
+===============================================================================
+^+ gamma.rueckgr.at              2   8   377   135  -1048us[-1048us] +/-   29ms
+^- 2b.ncomputers.org             2   8   377   204  -1141us[-1124us] +/-   50ms
+^+ www.kashra.com                2   8   377   139  +3483us[+3483us] +/-   18ms
+^+ stratum2-4.NTP.TechFak.U>     2   8   377   143  -2090us[-2073us] +/-   19ms
+^- zepto.mcl.gg                  2   7   377     9   -774us[ -774us] +/-   29ms
+^- mirrorhost.pw                 2   7   377    78   -660us[ -660us] +/-   53ms
+^- atto.mcl.gg                   2   7   377     8   -823us[ -823us] +/-   50ms
+^- static.140.107.46.78.cli>     2   8   377     9  -1503us[-1503us] +/-   45ms
+^- 4.53.160.75                   2   8   377   137    -11ms[  -11ms] +/-  117ms
+^- 37.44.185.42                  3   7   377    10  -3274us[-3274us] +/-   70ms
+^- bagnikita.com                 2   7   377    74  +3131us[+3131us] +/-   71ms
+^- europa.ellipse.net            2   8   377   204   -790us[ -773us] +/-   97ms
+^- tethys.hot-chilli.net         2   8   377   141   -797us[ -797us] +/-   59ms
+^- 66-232-97-8.static.hvvc.>     2   7   377   206  +1669us[+1686us] +/-  133ms
+^+ 85.199.214.102                1   8   377   205   +175us[ +192us] +/-   12ms
+^* 46-243-26-34.tangos.nl        1   8   377   141   -123us[ -106us] +/-   10ms
+^- pugot.canonical.com           2   8   377    21    -95us[  -95us] +/-   57ms
+^- alphyn.canonical.com          2   6   377    23  -1569us[-1569us] +/-   79ms
+^- golem.canonical.com           2   7   377    92  -1018us[-1018us] +/-   31ms
+^- chilipepper.canonical.com     2   8   377    21  -1106us[-1106us] +/-   27ms
+</computeroutput>
+<command>chronyc sourcestats</command>
+<computeroutput>
+210 Number of sources = 20
+Name/IP Address            NP  NR  Span  Frequency  Freq Skew  Offset  Std Dev
 ==============================================================================
-+stratum2-2.NTP. 129.70.130.70    2 u    5   64  377   68.461  -44.274 110.334
-+ntp2.m-online.n 212.18.1.106     2 u    5   64  377   54.629  -27.318  78.882
-*145.253.66.170  .DCFa.           1 u   10   64  377   83.607  -30.159  68.343
-+stratum2-3.NTP. 129.70.130.70    2 u    5   64  357   68.795  -68.168 104.612
-+europium.canoni 193.79.237.14    2 u   63   64  337   81.534  -67.968  92.792</computeroutput>
+gamma.rueckgr.at           25  15   32m     -0.007      0.142   -878us   106us
+2b.ncomputers.org          26  16   35m     -0.132      0.283  -1169us   256us
+www.kashra.com             25  15   32m     -0.092      0.259  +3426us   195us
+stratum2-4.NTP.TechFak.U>  25  14   32m     -0.018      0.130  -2056us    96us
+zepto.mcl.gg               13  11   21m     +0.148      0.196   -683us    66us
+mirrorhost.pw               6   5   645     +0.117      0.445   -591us    19us
+atto.mcl.gg                21  13   25m     -0.069      0.199   -904us   103us
+static.140.107.46.78.cli>  25  18   34m     -0.005      0.094  -1526us    78us
+4.53.160.75                25  10   32m     +0.412      0.110    -11ms    84us
+37.44.185.42               24  12   30m     -0.983      0.173  -3718us   122us
+bagnikita.com              17   7   31m     -0.132      0.217  +3527us   139us
+europa.ellipse.net         26  15   35m     +0.038      0.553   -473us   424us
+tethys.hot-chilli.net      25  11   32m     -0.094      0.110   -864us    88us
[phone].static.hvvc.>  20  11   35m     -0.116      0.165  +1561us   109us
+85.199.214.102             26  11   35m     -0.054      0.390   +129us   343us
[phone].tangos.nl     25  16   32m     +0.129      0.297   -307us   198us
+pugot.canonical.com        25  14   34m     -0.271      0.176   -143us   135us
+alphyn.canonical.com       17  11  1100     -0.087      0.360  -1749us   114us
+golem.canonical.com        23  12   30m     +0.057      0.370   -988us   229us
+chilipepper.canonical.com  25  18   34m     -0.084      0.224  -1116us   169us
+</computeroutput>
 </screen>
-
+  <para>
+      Certain chronyc commands are privileged and can not be run via the network without explicitly allowing them.
+      See section <emphasis>Command and monitoring access</emphasis> in <command>man chrony.conf</command> for more details.
+      A local admin can use <application>sudo</application> as usually as this will grant him access to the local admin socket <filename>/var/run/chrony/chronyd.sock</filename>.
+  </para>
 </sect3>
 
 <sect3 id="ntp-pps" status="review">
   <title>PPS Support</title>
   <para>
-Since 16.04 ntp supports PPS discipline which can be used to augment ntp with local timesources for better accuracy.
-For more details on configuration see the external pps ressource listed below.
+      Chrony supports various PPS types natively. It can use kernel PPS API as well as PTP hardware clock.
+      Most general GPS receivers can be leveraged via <application>GPSD</application>.
+      The latter (and potentially more) can be accessed via <emphasis>SHM</emphasis> or via a <emphasis>socket</emphasis> (recommended).
+      All of the above can be used to augment chrony with additional high quality time sources for better accuracy, jitter, drift, longer-or-short term accuracy (Usually each kind of clock type is good at one of those, but non-perfect at the others).
+      For more details on configuration see some of the external PPS/GPSD resource listed below.
   </para>
 </sect3>
 </sect2>
@@ -1225,7 +1310,7 @@
 	<itemizedlist>
 	  <listitem>
   	    <para>
-          See the <ulink url="https://help.ubuntu.com/community/UbuntuTime">Ubuntu Time</ulink> wiki page for more information.
+            <ulink url="https://chrony.tuxfamily.org/faq.html">Chrony FAQ</ulink>
         </para>
       </listitem>
 	  <listitem>
@@ -1235,6 +1320,11 @@
       </listitem>
 	  <listitem>
   	    <para>
+            <ulink url="http://www.pool.ntp.org/">The pool.ntp.org projecti, being a big virtual cluster of timeservers.</ulink>
+        </para>
+      </listitem>
+	  <listitem>
+  	    <para>
             <ulink url="https://www.freedesktop.org/software/systemd/man/timedatectl.html">Freedesktop.org info on timedatectl</ulink>
         </para>
       </listitem>
@@ -1245,7 +1335,12 @@
       </listitem>
 	  <listitem>
   	    <para>
-		    <ulink url="http://www.ntp.org/ntpfaq/NTP-s-config-adv.htm#S-CONFIG-ADV-PPS">ntp.org faq on configuring PPS</ulink>
+            <ulink url="http://www.catb.org/gpsd/gpsd-time-service-howto.html#_feeding_chrony_from_gpsd">Feeding chrony from GPSD</ulink>
+        </para>
+      </listitem>
+	  <listitem>
+  	    <para>
+          See the <ulink url="https://help.ubuntu.com/community/UbuntuTime">Ubuntu Time</ulink> wiki page for more information.
         </para>
       </listitem>
     </itemizedlist>