doc: Try to clarify automount dependency confusion

Arch recently upgraded systemd to 245.6. Shortly afterwards, users began
reporting[0] that systemd detected an ordering cycle, and they were
unable to log in. The reason they were unable to log in was because of
ordering cycle resolution:

    [...]
    systemd[1]: sysinit.target: Job systemd-tmpfiles-setup.service/start deleted to break ordering cycle starting with sysinit.target/start
    systemd[1]: sysinit.target: Job systemd-update-done.service/start deleted to break ordering cycle starting with sysinit.target/start
    systemd[1]: sysinit.target: Job systemd-journal-catalog-update.service/start deleted to break ordering cycle starting with sysinit.target/start
    systemd[1]: sysinit.target: Job local-fs.target/start deleted to break ordering cycle starting with sysinit.target/start
    systemd[1]: sysinit.target: Job systemd-tmpfiles-setup.service/start deleted to break ordering cycle starting with sysinit.target/start
    [...]

Whether the resolution did the right thing here or not is a longer-term
discussion, but in the interim we should at least make this distinction
between automount dependencies and mount dependencies clearer in the
documentation, so that users and distribution maintainers know what's
acceptable. In this case Arch actually backed out b3d7aef5 entirely and
released a new version due to the confusion.

Also see https://github.com/systemd/systemd-stable/issues/69.

0: https://bugs.archlinux.org/task/66908

diff --git a/man/systemd.automount.xml b/man/systemd.automount.xml
index 35690fd22a7539527ffb69a01b0d0650c2098dee..fd65f5da798b1377d2047a3c923e23f074f1c381 100644 (file)
--- a/man/systemd.automount.xml
+++ b/man/systemd.automount.xml
@@ -57,6 +57,12 @@
 
     <para>Automount units may be used to implement on-demand mounting
     as well as parallelized mounting of file systems.</para>
+
+    <para>Note that automount units are separate from the mount itself, so you
+    should not set <varname>After=</varname> or <varname>Requires=</varname>
+    for mount dependencies here. For example, you should not set
+    <varname>After=network-online.target</varname> or similar on network
+    filesystems. Doing so may result in an ordering cycle.</para>
   </refsect1>
 
   <refsect1>