man: Advertise systemd-time-wait-sync.service more (systemd#17729)

Minoru · web-flow · commit 1431b2f701f7 · 2020-12-19T11:17:49.000Z
* man: Advertise systemd-time-wait-sync.service more The description of time-sync.target says that NTP services *should* pull that target, but doesn't mention that e.g. systemd-timesyncd.service doesn't actually do that. As a result, time-sync.target is reached way earlier than people expect; see systemd#5097, systemd#8861, systemd#11008. systemd provides systemd-time-wait-sync.service to ameliorate this problem, but doesn't feature it prominently in relevant manpages. In fact, it's only mentioned in passing in systemd-timesyncd.service(8). As a result, I ended up re-implementing that service, and I'm not the first one: NixOS/nixpkgs#51338 This patch adds a mention right in the description of time-sync.target, which will hopefully raise awareness of this helper service.
diff --git a/man/systemd.special.xml b/man/systemd.special.xml
@@ -1018,7 +1018,16 @@
             in. systemd automatically adds dependencies of type
             <varname>After=</varname> for this target unit to all SysV
             init script service units with an LSB header referring to
-            the <literal>$time</literal> facility. </para>
+            the <literal>$time</literal> facility, and also to all timer
+            units with at least one <varname>OnCalendar=</varname>
+            directive. </para>
+
+            <para>This target might get reached before the clock is actually synchronized to an accurate reference
+            clock. To prevent that, enable
+            <citerefentry><refentrytitle>systemd-time-wait-sync.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+            if you're using
+            <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+            or an equivalent service for other NTP implementations.</para>
           </listitem>
         </varlistentry>
       </variablelist>
