From b5328434c91b10ad49647e2352e62b1fbdce329d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Sun, 24 Mar 2019 20:10:35 +0100 Subject: [PATCH] man: rework the description of Aliases and .wants/.requires directories The description of Alias= wasn't incorrect, but it sounded like Alias= creates a different type of dependency, while it's just a glorified way to create symlinks. Also recommend 'preset' in addition to 'enable'. Describe .wants/.requires dirs as equals, without implying that the [Install] section can only be used for .wants. The text was partially out of date (systemd-networkd.service now creates as alias in /etc, not /usr/lib, let's just not say anything about the full path). --- man/systemd.unit.xml | 58 ++++++++++++++++++++++++-------------------- 1 file changed, 32 insertions(+), 26 deletions(-) diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 0ac9ff4882..8307be1d33 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -123,34 +123,40 @@ do not need the prefix. Applications may use this to include additional information in the unit files. - Units can be aliased (have an alternative name), by creating a symlink from the new name - to the existing name in one of the unit search paths. For example, - systemd-networkd.service has the alias - dbus-org.freedesktop.network1.service, created during installation as the - symlink /usr/lib/systemd/system/dbus-org.freedesktop.network1.service. In - addition, unit files may specify aliases through the Alias= directive in the - [Install] section; those aliases are only effective when the unit is enabled. When the unit is - enabled, symlinks will be created for those names, and removed when the unit is disabled. For - example, reboot.target specifies - Alias=ctrl-alt-del.target, so when enabled it will be invoked whenever - CTRL+ALT+DEL is pressed. Alias names may be used in commands like enable, - disable, start, stop, - status, …, and in unit dependency directives Wants=, - Requires=, Before=, After=, …, with the - limitation that aliases specified through Alias= are only effective when the - unit is enabled. Aliases cannot be used with the preset command. + Units can be aliased (have an alternative name), by creating a symlink from the new name to the + existing name in one of the unit search paths. For example, systemd-networkd.service + has the alias dbus-org.freedesktop.network1.service, created during installation as + a symlink, so when systemd is asked through D-Bus to load + dbus-org.freedesktop.network1.service, it'll load + systemd-networkd.service. Alias names may be used in commands like + enable, disable, start, stop, + status, and similar, and in all unit dependency directives, including + Wants=, Requires=, Before=, + After=. Aliases cannot be used with the preset command. + + 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 + disabled. For example, reboot.target specifies + Alias=ctrl-alt-del.target, so when enabled, the symlink + /etc/systemd/systemd/ctrl-alt-del.service pointing to the + reboot.target file will be created, and when + CtrlAltDel is invoked, + systemd will look for the ctrl-alt-del.service and execute + reboot.service. systemd does not look at the [Install] section at + all during normal operation, so any directives in that section only have an effect through the symlinks + created during enablement. Along with a unit file foo.service, the directory - foo.service.wants/ may exist. All unit files symlinked from such a - directory are implicitly added as dependencies of type Wants= to the unit. - This 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/ directory of a unit file is - with the enable command of the - systemctl1 - tool which reads information from the [Install] section of unit files (see below). A similar - functionality exists for Requires= type dependencies as well, the directory - suffix is .requires/ in this case. + foo.service.wants/ may exist. All unit files symlinked from such a directory are + implicitly added as dependencies of type Wants= to the unit. Similar functionality + 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 with the enable or preset commands of + systemctl1. Along with a unit file foo.service, a "drop-in" directory foo.service.d/ may exist. All files with the suffix .conf from this