[systemd-devel] Examples in man pages (was: Re: service.d/.conf files and multi-valued options)
Zbigniew Jędrzejewski-Szmek
zbyszek at in.waw.pl
Sat Jan 24 06:18:28 PST 2015
On Sat, Jan 24, 2015 at 02:13:00PM +0100, Christian Seiler wrote:
> 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 <christian at 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>
The description is good. I wonder if it might better to inlcude a complete
unit here and discuss all lines, instead of just a snippet.
> + </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>
This part looks nice too.
Zbyszek
> +
> + <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