[systemd-devel] [PATCH v2 1/2] systemd.unit(5): add examples for common tasks

Christian Seiler christian at iwakd.de
Tue Jan 27 08:45:52 PST 2015


Add examples for (a) making units enableable and (b) overriding vendor
settings to the man page.
---
 man/systemd.unit.xml | 164 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 164 insertions(+)

diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index e820b33..8714f70 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -1574,6 +1574,170 @@
         </refsect1>
 
         <refsect1>
+                <title>Examples</title>
+
+                <example>
+                        <title>Making a unit enableable</title>
+
+                        <para>The following snippet (highlighted) makes
+                        a unit (e.g. <filename>foo.service</filename>)
+                        enableable 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
+                        converse <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=network.target remote-fs.target sqldb.service
+Requires=sqldb.service
+ConditionPathExists=/srv/webserver
+
+[Service]
+Type=notify
+ExecStart=/usr/sbin/some-fancy-httpd-server
+TimeoutStartSec=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 timeout for the
+                        service startup should be increased to 1
+                        minute.</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=network.target remote-fs.target sqldb.service <emphasis>memcached.service</emphasis>
+Requires=sqldb.service <emphasis>memcached.service</emphasis>
+ConditionPathExists=<emphasis>/srv/www</emphasis>
+
+[Service]
+Type=notify
+ExecStart=/usr/sbin/some-fancy-httpd-server
+<emphasis>TimeoutStartSec=1min</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 conditions and then re-add the condition we want
+ConditionPathExists=
+ConditionPathExists=/srv/www
+
+[Service]
+TimeoutStartSec=1min
+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>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
-- 
1.8.3.1



More information about the systemd-devel mailing list