From 8f6e28876538d5b9073725ba907add1f9f647c9f Mon Sep 17 00:00:00 2001
From: Peter Morrow <pemorrow@linux.microsoft.com>
Date: Mon, 7 Jun 2021 13:05:06 +0100
Subject: [PATCH] man: add details on overriding top level drop-ins

When using top level drop-ins it isn't immediately obvious that one can
make use of symlinking to disable a top-level drop in for a specific
unit.

Signed-off-by: Peter Morrow <pemorrow@linux.microsoft.com>
(cherry picked from commit 90a404f5d490eb4981851966f6a01f210fd5eb0d)
---
 man/systemd.unit.xml | 66 +++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 62 insertions(+), 4 deletions(-)

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index c5a2c441c7..47cd73616b 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -225,10 +225,12 @@
     where <replaceable>type</replaceable> may be e.g. <literal>service</literal> or <literal>socket</literal>,
     that allows altering or adding to the settings of all corresponding unit files on the system.
     The formatting and precedence of applying drop-in configurations follow what is defined above.
-    Configurations in <filename><replaceable>type</replaceable>.d/</filename> have the lowest precedence
-    compared to settings in the name specific override directories. So the contents of
-    <filename>foo-.service.d/10-override.conf</filename> would override
-    <filename>service.d/10-override.conf</filename>.</para>
+    Files in <filename><replaceable>type</replaceable>.d/</filename> have lower precedence compared
+    to files in name-specific override directories. The usual rules apply: multiple drop-in files
+    with different names are applied in lexicographic order, regardless of which of the directories
+    they reside in, so a file in <filename><replaceable>type</replaceable>.d/</filename> applies
+    to a unit only if there are no drop-ins or masks with that name in directories with higher
+    precedence. See Examples.</para>
 
     <para>Note that while systemd offers a flexible dependency system
     between units it is recommended to use this functionality only
@@ -2158,6 +2160,62 @@ PrivateTmp=yes</programlisting>
       to override the entire unit.</para>
 
     </example>
+
+    <example>
+      <title>Top level drop-ins with template units</title>
+
+      <para>Top level drop-ins can be used to change some aspect of all units
+      of a particular type. For example by creating the
+      <filename index='false'>/etc/systemd/system/service.d</filename>
+      directory with a drop-in file, the contents of the drop-in file can be
+      applied to all service units. We can take this further by having the
+      top-level drop-in instantiate a secondary helper unit. Consider for
+      example the following set of units and drop-in files where we install
+      an OnFailure dependency for all service units.</para>
+
+      <para>
+      <filename index='false'>/etc/systemd/system/failure-handler@.service</filename>:</para>
+
+      <programlisting>[Unit]
+Description=My failure handler for %i
+
+[Service]
+Type=oneshot
+# Perform some special action for when %i exits unexpectedly.
+ExecStart=/usr/sbin/myfailurehandler %i
+
+     </programlisting>
+
+     <para>We can then add an instance of the
+     <filename index='false'>failure-handler@.service</filename> as an
+     <varname>OnFailure=</varname> dependency for all service units.</para>
+
+    <para>
+    <filename index='false'>/etc/systemd/system/service.d/10-all.conf</filename>:</para>
+
+    <programlisting>[Unit]
+OnFailure=failure-handler@%n.service
+    </programlisting>
+
+    <para>Now, after running <command>systemctl daemon-reload</command> all
+    services will have acquired an <varname>OnFailure=</varname> dependency on
+    <filename index='false'>failure-handler@%n.service</filename>. The
+    template instance units will also have gained the dependency which results
+    in the creation of a recursive dependency chain. We can break the chain by
+    disabling the drop-in for the template instance units via a symlink to
+    <filename index='false'>/dev/null</filename>:</para>
+
+    <programlisting>
+<command>mkdir /etc/systemd/system/failure-handler@.service.d</command>
+<command>ln -s /dev/null /etc/systemd/system/failure-handler@.service.d/10-all.conf</command>
+<command>systemctl daemon-reload</command>
+    </programlisting>
+
+    <para>This ensures that if a <filename index='false'>failure-handler@.service</filename> instance fails it will not trigger an instance named
+    <filename index='false'>failure-handler@failure-handler.service.service</filename>.</para>
+
+    </example>
+
   </refsect1>
 
   <refsect1>
-- 
2.25.1