From 75695fb798ef34e5b1bd4a8b892f861b5d88601d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Mon, 16 Apr 2018 17:57:37 +0200 Subject: [PATCH] man: describe unit templating explicitly This patch is heavily based on the text suggested by archenemies in #3791. Fixes #3791. --- man/systemd.service.xml | 14 ++++++++++++++ man/systemd.unit.xml | 32 +++++++++++++++++--------------- 2 files changed, 31 insertions(+), 15 deletions(-) diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 1e309904fa..614a60489d 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -77,6 +77,20 @@ with SysV document. + + Service Templates + + It is possible for systemd services to take a single argument via the + service@argument.service + syntax. Such services are called "instantiated" services, while the unit definition without the + argument parameter is called a "template". An example could be a + dhcpcd@.service 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 + systemd.unit5 + for details. + + Implicit Dependencies diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 8b4a29445d..9264dd1472 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -115,6 +115,14 @@ Unit files are loaded from a set of paths determined during compilation, described in the next section. + 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 @ 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 @ and the unit type suffix. In the unit file itself, + the instance parameter may be referred to using %i and other specifiers, see + below. + Unit files may contain additional options on top of those listed here. If systemd encounters an unknown option, it will write a warning log message but continue loading the unit. If an @@ -204,21 +212,15 @@ socket-based activation which make dependencies implicit, resulting in a both simpler and more flexible system. - Optionally, units may be instantiated from a - template file at runtime. This allows creation of - multiple units from a single configuration file. If - systemd looks for a unit configuration file, it will - first search for the literal unit name in the - file system. If that yields no success and the unit - name contains an @ character, systemd will look for a - unit template that shares the same name but with the - instance string (i.e. the part between the @ character - and the suffix) removed. Example: if a service - getty@tty3.service is requested - and no file by that name is found, systemd will look - for getty@.service and - instantiate a service from that configuration file if - it is found. + As mentioned above, a unit may be instantiated from a template file. This allows creation + of multiple units from a single configuration file. If systemd looks for a unit configuration + file, it will first search for the literal unit name in the file system. If that yields no + success and the unit name contains an @ character, systemd will look for a + unit template that shares the same name but with the instance string (i.e. the part between the + @ character and the suffix) removed. Example: if a service + getty@tty3.service is requested and no file by that name is found, systemd + will look for getty@.service and instantiate a service from that + configuration file if it is found. To refer to the instance string from within the configuration file you may use the special %i