From ecd6c000d3a2e743a0f533d427250714c7593cf7 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. --- 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 c0c98a0e88a..372f5f8f7c4 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -138,7 +138,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 @@ -154,8 +154,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 @@ -175,11 +179,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 @@ -501,13 +512,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.