diff options
author | Peter Morrow <pemorrow@linux.microsoft.com> | 2021-06-07 13:05:06 +0100 |
---|---|---|
committer | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2021-06-08 17:03:03 +0200 |
commit | 90a404f5d490eb4981851966f6a01f210fd5eb0d (patch) | |
tree | 81a9b9cd96556a2458d703cd967d02116b7da409 /man/systemd.unit.xml | |
parent | d477a094e82c227ef6164b33d4eb3bcb22cc1473 (diff) | |
download | systemd-90a404f5d490eb4981851966f6a01f210fd5eb0d.tar.gz |
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>
Diffstat (limited to 'man/systemd.unit.xml')
-rw-r--r-- | man/systemd.unit.xml | 66 |
1 files changed, 62 insertions, 4 deletions
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 12e3610ab8..a20519a96f 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 @@ -2201,6 +2203,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> |