Merge lp:~paelzer/serverguide/serverguide-ntp-clarification into lp:serverguide/trunk

[Christian Ehrhardt ]

Improve NTP/Timesyncd content and separation in the serverguide (LP: #1604010)

[Doug Smythies (dsmythies)]

This all looks good. However...

The non-ascii character check fails:

$ scripts/ascii_checker.py --only-matching --encoding ascii serverguide/C/*.xml
  1111: ��� systemd-timesyncd.service - Network Time Synchronization

  1114: ������disable-with-time-daemon.conf

  1123: ������12379 /lib/systemd/systemd-timesyncd

--------------------------------------------------------------------------------
2018 lines in 'serverguide/C/network-config.xml', thereof 3 lines with non-ASCII characters.

and, the PDF compile has issues:

[INFO] FOUserAgent - Rendered page #53.
[INFO] FOUserAgent - Rendered page #54.
[WARN] FOUserAgent - Glyph "●" (0x25cf, H18533) not available in font "Courier".
[WARN] FOUserAgent - Glyph "└" (0x2514, SF020000) not available in font "Courier".
[WARN] FOUserAgent - Glyph "─" (0x2500, SF100000) not available in font "Courier".
[INFO] FOUserAgent - Rendered page #55.
[INFO] FOUserAgent - Rendered page #56.

I will change those characters to ASCII to try to achieve a similar look to the original output.

See also:
https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Repository/Members-Serverguide#ASCII_Policy

review: Approve

[Christian Ehrhardt  (paelzer)]

Thanks Doug,
it was a copy and paste form my terminal and so I didn't realize I had to
postprocess it.
Thanks for fixing it up and the link to the ascii policy - I hope I do
better on these details next time!

On Sun, Jul 2, 2017 at 7:42 PM, <email address hidden> wrote:

> The proposal to merge lp:~paelzer/serverguide/serverguide-ntp-clarification
> into lp:serverguide has been updated.
>
> Status: Needs review => Merged
>
> For more details, see:
> https://code.launchpad.net/~paelzer/serverguide/
> serverguide-ntp-clarification/+merge/326283
> --
> You are the owner of lp:~paelzer/serverguide/
> serverguide-ntp-clarification.
>

--
Christian Ehrhardt
Software Engineer, Ubuntu Server
Canonical Ltd

[Doug Smythies (dsmythies)]

> it was a copy and paste from my terminal and so
> I didn't realize I had to postprocess it.
> Thanks for fixing it up and the link to the ascii
> policy - I hope I do better on these details next time!

The non ASCII character thing rarely comes up.
The notes about it are on the "how to be a doc committer for serverguide" wiki page, and not the "how to contribute to the serverguide" wiki page. Perhaps I should add a note on the latter wiki page pointing to the former wiki page.

=== modified file 'serverguide/C/network-config.xml'
--- serverguide/C/network-config.xml	2017-03-15 10:13:19 +0000
+++ serverguide/C/network-config.xml	2017-06-26 10:19:18 +0000
@@ -1055,7 +1055,7 @@
     </sect1>
 
 	<sect1 id="NTP" status="review">
-		<title>Time Synchronisation with NTP</title>
+		<title>Time Synchronisation</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.  
 </para>
@@ -1063,92 +1063,103 @@
 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 uses ntpdate and ntpd. 
+Ubuntu by default uses <emphasis>timedatectl / timesyncd</emphasis> to synchronize time and users can optionally use ntpd to serve network time info.
 </para>
 
-<sect2 id="timedatectl" status="review">
-<title>timedatectl</title>
-	<para>
-		In recent Ubuntu releases <emphasis>timedatectl</emphasis> replaces <emphasis>ntpdate</emphasis>.
-		By default <emphasis>timedatectl</emphasis> syncs the time once on boot and later on uses socket activation to recheck once network connections become active.
-</para>
-	<para>
-		If <emphasis>ntpdate / ntp</emphasis> is installed <emphasis>timedatectl</emphasis> steps back to let you keep your old setup.
+<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>.
+	</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>.
+		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.
 		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>
-</sect2>
+	</para>
+	<para>
+		<application>ntpdate</application> is considered deprecated in favour of <application>timedatectl</application> and thereby no more installed by default.
+	</para>
 
-<sect2 id="timesyncd" status="review">
-<title>timesyncd</title>
-	<para>
-		In recent Ubuntu releases <emphasis>timesyncd</emphasis> replaces the client portion of <emphasis>ntpd</emphasis>.
-		By default <emphasis>timesyncd</emphasis> regularly checks and keeps the time in sync.
-		It also stores time updates locally, so that after reboots monotonically advances if applicable.
-</para>
-	<para>
-		The current status of time and time configuration via <emphasis>timedatectl</emphasis> and <emphasis>timesyncd</emphasis> can be checked with <emphasis>timedatectl status</emphasis>.
-</para>
-<programlisting>
-timedatectl status
-      Local time: Fri 2016-04-29 06:32:57 UTC
-  Universal time: Fri 2016-04-29 06:32:57 UTC
-        RTC time: Fri 2016-04-29 07:44:02
-       Time zone: Etc/UTC (UTC, +0000)
+<sect3 id="timedate-config" status="review">
+<title>Configuring timedatectl and timesyncd</title>
+	<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>
+$ 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: no
+NTP synchronized: yes
  RTC in local TZ: no
-</programlisting>
-	<para>
-		If NTP is installed and replaces the activity of <emphasis>timedatectl</emphasis> the line "NTP synchronized" is set to yes.
-</para>
-	<para>
-		The nameserver to fetch time for <emphasis>timedatectl</emphasis> and <emphasis>timesyncd</emphasis> from can be specified in /etc/systemd/timesyncd.conf and with flexible additional config files in /etc/systemd/timesyncd.conf.d/.
-</para>
-</sect2>
-
-<sect2 id="ntpdate" status="review">
-<title>ntpdate</title>
-	<para>
-		<emphasis>ntpdate</emphasis> is considered deprecated in favour of <emphasis>timedatectl</emphasis> and thereby no more installed by default.
-		If installed it will run once at boot time to set up your time according to Ubuntu's NTP server.
-		Later on anytime a new interface comes up it retries to update the time - while doing so it will try to slowly drift time as long as the delta it has to cover isn't too big.
-		That behaviour can be controlled with the <emphasis>-B/-b</emphasis> switches.
-</para>
-<programlisting>
-ntpdate ntp.ubuntu.com
-</programlisting>
+</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.
+</para>
+<para>
+        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
+   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
+     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
+   CGroup: /system.slice/systemd-timesyncd.service
+           └─12379 /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).
+</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.
+</para>
+</sect3>
+
 </sect2>
 
 <sect2 id="timeservers" status="review">
-   <title>timeservers</title>
+   <title>Serving NTP</title>
    <para>
-	   By default the systemd based tools request time information at ntp.ubuntu.com.
-	   In classic ntpd based service uses the pool of [0-3].ubuntu.pool.ntp.org
-	   Of the pool number 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.
+       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.
    </para>
-</sect2>
 
-<sect2 id="ntpd" status="review">
+<sect3 id="ntpd" status="review">
    <title>ntpd</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 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.
    </para>
-</sect2>
-<sect2 id="ntp-installation" status="review">
+</sect3>
+
+<sect3 id="ntp-installation" status="review">
    <title>Installation</title>
    <para>
-   To install ntpd, from a terminal prompt enter: 
+   To install ntpd, from a terminal prompt enter:
    </para>
-
 <screen>
 <command>sudo apt install ntp</command>
 </screen>
+</sect3>
 
-</sect2>
-<sect2 id="timeservers-conf" status="review">
+<sect3 id="timeservers-conf" status="review">
   <title>Configuration</title>
 
   <para>
@@ -1173,8 +1184,14 @@
 <screen>
 <command>sudo systemctl reload ntp.service</command>
 </screen>
-</sect2>
-<sect2 id="ntp-status" status="review">
+<para>
+	   Of the pool number 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>
+
+</sect3>
+
+<sect3 id="ntp-status" status="review">
   <title>View status</title>
   <para>
   Use ntpq to see more info: 
@@ -1190,14 +1207,15 @@
 +europium.canoni 193.79.237.14    2 u   63   64  337   81.534  -67.968  92.792</computeroutput>
 </screen>
 
-</sect2>
+</sect3>
 
-<sect2 id="ntp-pps" status="review">
+<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.
   </para>
+</sect3>
 </sect2>
 
 
@@ -1217,6 +1235,16 @@
       </listitem>
 	  <listitem>
   	    <para>
+            <ulink url="https://www.freedesktop.org/software/systemd/man/timedatectl.html">Freedesktop.org info on timedatectl</ulink>
+        </para>
+      </listitem>
+	  <listitem>
+  	    <para>
+            <ulink url="https://www.freedesktop.org/software/systemd/man/systemd-timesyncd.service.html#">Freedesktop.org info on systemd-timesyncd service</ulink>
+        </para>
+      </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>
         </para>
       </listitem>