man: document the new dash truncation drop-in directories

1 files changed, 18 insertions, 9 deletions

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index 9cabc3c4f8..2baf9d17e8 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -189,15 +189,24 @@
     suffix is <filename>.requires/</filename> in this case.</para>
 
     <para>Along with a unit file <filename>foo.service</filename>, a "drop-in" directory
-    <filename>foo.service.d/</filename> may exist. All files with the suffix
-    <literal>.conf</literal> from this directory will be parsed after the file itself is
-    parsed. This is useful to alter or add configuration settings for a unit, without having to
-    modify unit files. Each drop-in file must have appropriate section headers. Note that for
-    instantiated units, this logic will first look for the instance <literal>.d/</literal>
-    subdirectory and read its <literal>.conf</literal> files, followed by the template
-    <literal>.d/</literal> subdirectory and the <literal>.conf</literal> files there.</para>
-
-    <para>In addition to <filename>/etc/systemd/system</filename>, the drop-in <literal>.d</literal>
+    <filename>foo.service.d/</filename> may exist. All files with the suffix <literal>.conf</literal> from this
+    directory will be parsed after the unit file itself is parsed. This is useful to alter or add configuration
+    settings for a unit, without having to modify unit files. Drop-in files must contain appropriate section
+    headers. For instantiated units, this logic will first look for the instance <literal>.d/</literal> subdirectory
+    (e.g. <literal>foo@bar.service.d/</literal>) and read its <literal>.conf</literal> files, followed by the template
+    <literal>.d/</literal> subdirectory (e.g. <literal>foo@.service.d/</literal>) and the <literal>.conf</literal>
+    files there. Moreover for units names containing dashes (<literal>-</literal>), the set of directories generated by
+    truncating the unit name after all dashes is searched too. Specifically, for a unit name
+    <filename>foo-bar-baz.service</filename> not only the the regular drop-in directory
+    <filename>foo-bar-baz.service.d/</filename> is searched but also both <filename>foo-bar-.service.d/</filename> and
+    <filename>foo-.service.d/</filename>. This is useful for defining common drop-ins for a set of related units, whose
+    names begin with a common prefix. This scheme is particularly useful for mount, automount and slice units, whose
+    systematic naming structure is built around dashes as component separators. Note that equally named drop-in files
+    further down the prefix hierarchy override those further up,
+    i.e. <filename>foo-bar-.service.d/10-override.conf</filename> overrides
+    <filename>foo-.service.d/10-override.conf</filename>.</para>
+
+    <para>In addition to <filename>/etc/systemd/system</filename>, the drop-in <literal>.d/</literal>
     directories for system services can be placed in <filename>/usr/lib/systemd/system</filename> or
     <filename>/run/systemd/system</filename> directories. Drop-in files in <filename>/etc</filename>
     take precedence over those in <filename>/run</filename> which in turn take precedence over those