Am 23.01.2015 um 15:20 schrieb Zbigniew Jędrzejewski-Szmek:
> I think it would be great to have an Examples section in
> systemd.{unit, service,socket,path,...} giving a semi-realistic
> example of a unit that can serve as a template. For systemd.socket
> there should be two: an Accept=yes and Accept=no.
I've attached a git format-patch of adding an example section to
systemd.unit for the two most common tasks about modifying units, to see
whether you consider that style acceptable.
Christian
From 7f448c58296d3b10392fa98975d28f13745bb845 Mon Sep 17 00:00:00 2001
From: Christian Seiler <christ...@iwakd.de>
Date: Sat, 24 Jan 2015 14:04:03 +0100
Subject: [PATCH] systemd.unit(5): add examples for common tasks
Add examples for (a) making units enableable and (b) overriding vendor
settings to the man page.
---
man/systemd.unit.xml | 153 +++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 153 insertions(+)
diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml
index bf0deb1..1d89bc9 100644
--- a/man/systemd.unit.xml
+++ b/man/systemd.unit.xml
@@ -1574,6 +1574,159 @@
</refsect1>
<refsect1>
+ <title>Examples</title>
+
+ <example>
+ <title>Making a unit enableable</title>
+
+ <para>The following snippet makes a unit
+ (e.g. <filename>foo.service</filename>)
+ enableable via
+ <command>systemctl enable</command>:</para>
+
+ <programlisting>[Install]
+WantedBy=multi-user.target</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, such as
+ <varname>After=</varname> or
+ <varname>Before=</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 nss-lookup.target sqldb.service
+Requires=sqldb.service
+
+[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>nss-lookup.target</filename> might
+ take a long time to be reached at boot. But
+ because of the local configuration it is not
+ actually required for the service to run, so
+ the administrator would like to remove it from
+ the dependencies, to make the service start up
+ faster. 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
+<emphasis>After=network.target remote-fs.target sqldb.service memcached.service</emphasis>
+Requires=sqldb.service <emphasis>memcached.service</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]
+# reset After= list to empty to remove nss-lookup.target
+After=
+After=network.target remote-fs.target sqldb.service memcached.service
+# since Requires= is not reset, this is just appended
+Requires=memcached.service
+
+[Service]
+TimeoutStartSec=1min
+PrivateTmp=yes</programlisting>
+ </example>
+ </refsect1>
+
+ <refsect1>
<title>See Also</title>
<para>
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
--
1.8.3.1
_______________________________________________
systemd-devel mailing list
systemd-devel@lists.freedesktop.org
http://lists.freedesktop.org/mailman/listinfo/systemd-devel
