From 842c3bade0b593e5c4eabbe1c18dfab503683cc6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 10 Mar 2022 21:33:25 +0100 Subject: [PATCH] man: fix invalid description of template handling in WantedBy= We don't need to talk about Alias=. The approach of using Alias= to enable units is still supported, but hasn't been advertised as the way to do thing for many years. Using it as an explanation is just confusing. Also, the description of templated units did not take DefaultInstance= into account. It is updated and extended. (cherry picked from commit 17a2679e9925c9ec3c5764d01def92c5627973e4) Related: #2082131 --- man/systemd.unit.xml | 53 +++++++++++++++++------------------ test/test-systemctl-enable.sh | 49 ++++++++++++++++++++++++++++++++ 2 files changed, 74 insertions(+), 28 deletions(-) diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 2e6261c1ed..caebaecfdc 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -1906,34 +1906,31 @@ WantedBy= RequiredBy= - This option may be used more than once, or a - space-separated list of unit names may be given. A symbolic - link is created in the .wants/ or - .requires/ directory of each of the - listed units when this unit is installed by systemctl - enable. This has the effect that a dependency of - type Wants= or Requires= - is added from the listed unit to the current unit. The primary - result is that the current unit will be started when the - listed unit is started. See the description of - Wants= and Requires= in - the [Unit] section for details. - - WantedBy=foo.service in a service - bar.service is mostly equivalent to - Alias=foo.service.wants/bar.service in the - same file. In case of template units listing non template units, - systemctl enable must be called with an - instance name, and this instance will be added to the - .wants/ or - .requires/ list of the listed unit. E.g. - WantedBy=getty.target in a service - getty@.service will result in - systemctl enable getty@tty2.service - creating a - getty.target.wants/getty@tty2.service - link to getty@.service. - + This option may be used more than once, or a space-separated list of unit names may + be given. A symbolic link is created in the .wants/ or + .requires/ directory of each of the listed units when this unit is installed by + systemctl enable. This has the effect of a dependency of type + Wants= or Requires= being added from the listed unit to the + current unit. The primary result is that the current unit will be started when the listed unit is + started, see the description of Wants= and Requires= in the + [Unit] section for details. + + In case of template units listing non template units, the listing unit must have + DefaultInstance= set, or systemctl enable must be called with + an instance name. The instance (default or specified) will be added to the + .wants/ or .requires/ list of the listed unit. For example, + WantedBy=getty.target in a service getty@.service will result + in systemctl enable getty@tty2.service creating a + getty.target.wants/getty@tty2.service link to + getty@.service. This also applies to listing specific instances of templated + units: this specific instance will gain the dependency. A template unit may also list a template + unit, in which case a generic dependency will be added where each instance of the listing unit will + have a dependency on an instance of the listed template with the same instance value. For example, + WantedBy=container@.target in a service monitor@.service will + result in systemctl enable monitor@.service creating a + container@.target.wants/monitor@.service link to + monitor@.service, which applies to all instances of + container@.target. diff --git a/test/test-systemctl-enable.sh b/test/test-systemctl-enable.sh index 4117436462..3aa61222a8 100644 --- a/test/test-systemctl-enable.sh +++ b/test/test-systemctl-enable.sh @@ -324,6 +324,31 @@ test ! -h "$root/etc/systemd/system/services.target.wants/templ1@333.service" test ! -h "$root/etc/systemd/system/services.target.wants/templ1@one.service" test ! -h "$root/etc/systemd/system/services.target.wants/templ1@two.service" +: -------template enablement for another template------------- +cat >"$root/etc/systemd/system/templ2@.service" <"$root/etc/systemd/system/link4.service" <&2; exit 1; } +: -------specifiers in WantedBy------------------------------- +# We don't need to repeat all the tests. Let's do a basic check that specifier +# expansion is performed. + +cat >"$root/etc/systemd/system/some-some-link7.socket" <