From 2c9079ca0eaa2a1df2a1775c28fa7a49785999df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Mon, 28 Mar 2022 11:46:38 +0200 Subject: [PATCH] man: clarify the descriptions of aliases and linked unit files This just describes the rules that are implemented by the manager, and this pull request does not change any of them. (cherry picked from commit ecd6c000d3a2e743a0f533d427250714c7593cf7) Related: #2082131 --- man/systemd.unit.xml | 58 ++++++++++++++++++++++++++++++++------------ 1 file changed, 43 insertions(+), 15 deletions(-) diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 2a44b8cfd8..4ba602b5ad 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -140,7 +140,7 @@ a symlink, so when systemd is asked through D-Bus to load dbus-org.freedesktop.network1.service, it'll load systemd-networkd.service. As another example, default.target — - the default system target started at boot — is commonly symlinked (aliased) to either + the default system target started at boot — is commonly aliased to either multi-user.target or graphical.target to select what is started by default. Alias names may be used in commands like disable, start, stop, status, and similar, and in all @@ -156,8 +156,12 @@ template instance (e.g. alias@inst.service) may be a symlink to different template (e.g. template@inst.service). In that case, just this specific instance is aliased, while other instances of the template (e.g. alias@foo.service, - alias@bar.service) are not aliased. Those rule preserve the requirement that the - instance (if any) is always uniquely defined for a given unit and all its aliases. + alias@bar.service) are not aliased. Those rules preserve the requirement that the + instance (if any) is always uniquely defined for a given unit and all its aliases. The target of alias + symlink must point to a valid unit file location, i.e. the symlink target name must match the symlink + source name as described, and the destination path must be in one of the unit search paths, see UNIT FILE + LOAD PATH section below for more details. Note that the target file may not exist, i.e. the symlink may + be dangling. Unit files may specify aliases through the Alias= directive in the [Install] section. When the unit is enabled, symlinks will be created for those names, and removed when the unit is @@ -177,11 +181,18 @@ exists for Requires= type dependencies as well, the directory suffix is .requires/ in this case. This functionality is useful to hook units into the start-up of other units, without having to modify their unit files. For details about the semantics of - Wants=, see below. The preferred way to create symlinks in the - .wants/ or .requires/ directory of a unit file is by embedding - the dependency in [Install] section of the target unit, and creating the symlink in the file system with - the enable or preset commands of - systemctl1. + Wants= and Requires=, see below. The preferred way to create + symlinks in the .wants/ or .requires/ directories is by + specifying the dependency in [Install] section of the target unit, and creating the symlink in the file + system with the enable or preset commands of + systemctl1. The + target can be a normal unit (either plain or a specific instance of a template unit). In case when the + source unit is a template, the target can also be a template, in which case the instance will be + "propagated" to the target unit to form a valid unit instance. The target of symlinks in + .wants/ or .requires/ must thus point to a valid unit file + location, i.e. the symlink target name must satisfy the described requirements, and the destination path + must be in one of the unit search paths, see UNIT FILE LOAD PATH section below for more details. Note + that the target file may not exist, i.e. the symlink may be dangling. Along with a unit file foo.service, a "drop-in" directory foo.service.d/ may exist. All files with the suffix @@ -503,13 +514,30 @@ systemd-analyze --user unit-paths - Moreover, additional units might be loaded into systemd from - directories not on the unit load path by creating a symlink pointing to a - unit file in the directories. You can use systemctl link - for this operation. See - systemctl1 - for its usage and precaution. - + Moreover, additional units might be loaded into systemd from directories not on the unit load path + by creating a symlink pointing to a unit file in the directories. You can use systemctl + link for this; see + systemctl1. The file + system where the linked unit files are located must be accessible when systemd is started (e.g. anything + underneath /home/ or /var/ is not allowed, unless those + directories are located on the root file system). + + It is important to distinguish "linked unit files" from "unit file aliases": any symlink where the + symlink target is within the unit load path becomes an alias: the source name and + the target file name must satisfy specific constraints listed above in the discussion of aliases, but the + symlink target doesn't have to exist, and in fact the symlink target path is not used, except to check + whether the target is within the unit load path. In constrast, a symlink which goes outside of the unit + load path signifies a linked unit file. The symlink is followed when loading the file, but the + destination name is otherwise unused (and may even not be a valid unit file name). For example, symlinks + /etc/systemd/system/alias1.service → service1.service, + /etc/systemd/system/alias2.service → /usr/lib/systemd/service1.service, + /etc/systemd/system/alias3.service → /etc/systemd/system/service1.service + are all valid aliases and service1.service will have + four names, even if the unit file is located at + /run/systemd/system/service1.service. In contrast, + a symlink /etc/systemd/system/link1.service → ../link1_service_file + means that link1.service is a "linked unit" and the contents of + /etc/systemd/link1_service_file provide its configuration.