picnoir/Systemd
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

man: describe unit templating explicitly

Browse source 
This patch is heavily based on the text suggested by
archenemies in #3791.

Fixes #3791.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2018-04-16 17:57:37 +02:00
parent 2116134b04
commit 75695fb798
2 changed files with 31 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

14
man/systemd.service.xml
View file

@ -77,6 +77,20 @@
with SysV</ulink> document.</para> with SysV</ulink> document.</para>
</refsect1> </refsect1>
<refsect1>
<title>Service Templates</title>
<para>It is possible for <command>systemd</command> services to take a single argument via the
<literal><replaceable>service</replaceable>@<replaceable>argument</replaceable>.service</literal>
syntax. Such services are called "instantiated" services, while the unit definition without the
<replaceable>argument</replaceable> parameter is called a "template". An example could be a
<filename>dhcpcd@.service</filename> service template which takes a network interface as a
parameter to form an instantiated service. Within the service file, this parameter or "instance
name" can be accessed with %-specifiers. See
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details.</para>
</refsect1>
<refsect1> <refsect1>
<title>Implicit Dependencies</title> <title>Implicit Dependencies</title>

32
man/systemd.unit.xml
View file

@ -115,6 +115,14 @@
<para>Unit files are loaded from a set of paths determined during <para>Unit files are loaded from a set of paths determined during
compilation, described in the next section.</para> compilation, described in the next section.</para>
<para>Unit files can be parameterized by a single argument called the "instance name". The unit
is then constructed based on a "template file" which serves as the definition of multiple
services or other units. A template unit must have a single <literal>@</literal> at the end of
the name (right before the type suffix). The name of the full unit is formed by inserting the
instance name between <literal>@</literal> and the unit type suffix. In the unit file itself,
the instance parameter may be referred to using <literal>%i</literal> and other specifiers, see
below.</para>
<para>Unit files may contain additional options on top of those <para>Unit files may contain additional options on top of those
listed here. If systemd encounters an unknown option, it will listed here. If systemd encounters an unknown option, it will
write a warning log message but continue loading the unit. If an write a warning log message but continue loading the unit. If an
@ -204,21 +212,15 @@
socket-based activation which make dependencies implicit, socket-based activation which make dependencies implicit,
resulting in a both simpler and more flexible system.</para> resulting in a both simpler and more flexible system.</para>
<para>Optionally, units may be instantiated from a <para>As mentioned above, a unit may be instantiated from a template file. This allows creation
template file at runtime. This allows creation of of multiple units from a single configuration file. If systemd looks for a unit configuration
multiple units from a single configuration file. If file, it will first search for the literal unit name in the file system. If that yields no
systemd looks for a unit configuration file, it will success and the unit name contains an <literal>@</literal> character, systemd will look for a
first search for the literal unit name in the unit template that shares the same name but with the instance string (i.e. the part between the
file system. If that yields no success and the unit <literal>@</literal> character and the suffix) removed. Example: if a service
name contains an <literal>@</literal> character, systemd will look for a <filename>getty@tty3.service</filename> is requested and no file by that name is found, systemd
unit template that shares the same name but with the will look for <filename>getty@.service</filename> and instantiate a service from that
instance string (i.e. the part between the <literal>@</literal> character configuration file if it is found.</para>
and the suffix) removed. Example: if a service
<filename>getty@tty3.service</filename> is requested
and no file by that name is found, systemd will look
for <filename>getty@.service</filename> and
instantiate a service from that configuration file if
it is found.</para>
<para>To refer to the instance string from within the <para>To refer to the instance string from within the
configuration file you may use the special <literal>%i</literal> configuration file you may use the special <literal>%i</literal>