From 92b1e2256a3aca86a49ee5961cde9b8d27c0e0f0 Mon Sep 17 00:00:00 2001
From: Christian Seiler <christian@iwakd.de>
Date: Sat, 24 Jan 2015 14:04:03 +0100
Subject: [PATCH] man: systemd.unit(5): add examples for common tasks

Add examples for (a) how to allow units to be enabled and (b)
overriding vendor settings to the man page.
---
 man/systemd.unit.xml | 165 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 165 insertions(+)

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index e820b3308..9704d6f22 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -1573,6 +1573,171 @@
 		running in <option>--user</option> mode.</para>
         </refsect1>
 
+        <refsect1>
+                <title>Examples</title>
+
+                <example>
+                        <title>Allowing units to be enabled</title>
+
+                        <para>The following snippet (highlighted)
+                        allows a unit (e.g.
+                        <filename>foo.service</filename>) to be
+                        enabled via
+                        <command>systemctl enable</command>:</para>
+
+                        <programlisting>[Unit]
+Description=Foo
+
+[Service]
+ExecStart=/usr/sbin/foo-daemon
+
+<emphasis>[Install]</emphasis>
+<emphasis>WantedBy=multi-user.target</emphasis></programlisting>
+
+                        <para>After running
+                        <command>systemctl enable</command>, a symlink
+                        <filename>/etc/systemd/system/multi-user.target.wants/foo.service</filename>
+                        linking to the actual unit will be created. It
+                        tells systemd to pull in the unit when starting
+                        <filename>multi-user.target</filename>. The
+                        inverse <command>systemctl disable</command>
+                        will remove that symlink again.</para>
+                </example>
+
+                <example>
+                        <title>Overriding vendor settings</title>
+
+                        <para>There are two methods of overriding
+                        vendor settings in unit files: copying the unit
+                        file from
+                        <filename>/usr/lib/systemd/system</filename>
+                        to <filename>/etc/systemd/system</filename> and
+                        modifying the chosen settings. Alternatively,
+                        one can create a directory named
+                        <filename><replaceable>unit</replaceable>.d/</filename>
+                        within
+                        <filename>/etc/systemd/system</filename> and
+                        place a drop-in file
+                        <filename><replaceable>name</replaceable>.conf</filename>
+                        there that only changes the specific settings
+                        one is interested in. Note that multiple such
+                        drop-in files are read if present.</para>
+
+                        <para>The advantage of the first method is
+                        that one easily overrides the complete unit,
+                        the vendor unit is not parsed at all anymore.
+                        It has the disadvantage that improvements to
+                        the unit file by the vendor are not
+                        automatically incorporated on updates.</para>
+
+                        <para>The advantage of the second method is
+                        that one only overrides the settings one
+                        specifically wants, where updates to the unit
+                        by the vendor automatically apply. This has the
+                        disadvantage that some future updates by the
+                        vendor might be incompatible with the local
+                        changes.</para>
+
+                        <para>Note that for drop-in files, if one wants
+                        to remove entries from a setting that is parsed
+                        as a list (and is not a dependency), such as
+                        <varname>ConditionPathExists=</varname> (or
+                        e.g. <varname>ExecStart=</varname> in service
+                        units), one needs to first clear the list
+                        before re-adding all entries except the one
+                        that is to be removed. See below for an
+                        example.</para>
+
+                        <para>This also applies for user instances of
+                        systemd, but with different locations for the
+                        unit files. See the section on unit load paths
+                        for further details.</para>
+
+                        <para>Suppose there is a vendor-supplied unit
+                        <filename>/usr/lib/systemd/system/httpd.service</filename>
+                        with the following contents:</para>
+
+                        <programlisting>[Unit]
+Description=Some HTTP server
+After=remote-fs.target sqldb.service
+Requires=sqldb.service
+AssertPathExists=/srv/webserver
+
+[Service]
+Type=notify
+ExecStart=/usr/sbin/some-fancy-httpd-server
+Nice=5
+
+[Install]
+WantedBy=multi-user.target</programlisting>
+
+                        <para>Now one wants to change some settings as
+                        an administrator: firstly, in the local setup,
+                        <filename>/srv/webserver</filename> might not
+                        exit, because the HTTP server is configured to
+                        use <filename>/srv/www</filename> instead.
+                        Secondly, the local configuration makes the
+                        HTTP server also depend on a memory cache
+                        service,
+                        <filename>memcached.service</filename>, that
+                        should be pulled in
+                        (<varname>Requires=</varname>) and also be
+                        ordered appropriately
+                        (<varname>After=</varname>). Thirdly, in order
+                        to harden the service a bit more, the
+                        administrator would like to set the
+                        <varname>PrivateTmp=</varname>
+                        setting (see
+                        <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+                        for details). And lastly, the administrator
+                        would like to reset the niceness of the service
+                        to its default value of 0.</para>
+
+                        <para>The first possibility is to copy the unit
+                        file to
+                        <filename>/etc/systemd/system/httpd.service</filename>
+                        and change the chosen settings:</para>
+
+                        <programlisting>[Unit]
+Description=Some HTTP server
+After=remote-fs.target sqldb.service <emphasis>memcached.service</emphasis>
+Requires=sqldb.service <emphasis>memcached.service</emphasis>
+AssertPathExists=<emphasis>/srv/www</emphasis>
+
+[Service]
+Type=notify
+ExecStart=/usr/sbin/some-fancy-httpd-server
+<emphasis>Nice=0</emphasis>
+<emphasis>PrivateTmp=yes</emphasis>
+
+[Install]
+WantedBy=multi-user.target</programlisting>
+
+                        <para>Alternatively, the administrator could
+                        create a drop-in file
+                        <filename>/etc/systemd/system/httpd.service.d/local.conf</filename>
+                        with the following contents:</para>
+
+                        <programlisting>[Unit]
+After=memcached.service
+Requires=memcached.service
+# Reset all assertions and then re-add the condition we want
+AssertPathExists=
+AssertPathExists=/srv/www
+
+[Service]
+Nice=0
+PrivateTmp=yes</programlisting>
+
+                        <para>Note that dependencies
+                        (<varname>After=</varname>, etc.) cannot be
+                        reset to an empty list, so dependencies can
+                        only be added in drop-ins. If you want to
+                        remove dependencies, you have to override the
+                        entire unit.</para>
+                </example>
+        </refsect1>
+
         <refsect1>
                 <title>See Also</title>
                 <para>
-- 
2.30.2