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).
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2019-03-24 20:10:35 +01:00
parent 52f4b5ac8a
commit b5328434c9

View File

@ -123,34 +123,40 @@
do not need the prefix. Applications may use this to include
additional information in the unit files.</para>
<para>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,
<filename>systemd-networkd.service</filename> has the alias
<filename>dbus-org.freedesktop.network1.service</filename>, created during installation as the
symlink <filename>/usr/lib/systemd/system/dbus-org.freedesktop.network1.service</filename>. In
addition, unit files may specify aliases through the <varname>Alias=</varname> 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, <filename>reboot.target</filename> specifies
<varname>Alias=ctrl-alt-del.target</varname>, so when enabled it will be invoked whenever
CTRL+ALT+DEL is pressed. Alias names may be used in commands like <command>enable</command>,
<command>disable</command>, <command>start</command>, <command>stop</command>,
<command>status</command>, …, and in unit dependency directives <varname>Wants=</varname>,
<varname>Requires=</varname>, <varname>Before=</varname>, <varname>After=</varname>, …, with the
limitation that aliases specified through <varname>Alias=</varname> are only effective when the
unit is enabled. Aliases cannot be used with the <command>preset</command> command.</para>
<para>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, <filename>systemd-networkd.service</filename>
has the alias <filename>dbus-org.freedesktop.network1.service</filename>, created during installation as
a symlink, so when <command>systemd</command> is asked through D-Bus to load
<filename>dbus-org.freedesktop.network1.service</filename>, it'll load
<filename>systemd-networkd.service</filename>. Alias names may be used in commands like
<command>enable</command>, <command>disable</command>, <command>start</command>, <command>stop</command>,
<command>status</command>, and similar, and in all unit dependency directives, including
<varname>Wants=</varname>, <varname>Requires=</varname>, <varname>Before=</varname>,
<varname>After=</varname>. Aliases cannot be used with the <command>preset</command> command.</para>
<para>Unit files may specify aliases through the <varname>Alias=</varname> 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, <filename>reboot.target</filename> specifies
<varname>Alias=ctrl-alt-del.target</varname>, so when enabled, the symlink
<filename>/etc/systemd/systemd/ctrl-alt-del.service</filename> pointing to the
<filename>reboot.target</filename> file will be created, and when
<keycombo><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>Del</keycap></keycombo> is invoked,
<command>systemd</command> will look for the <filename>ctrl-alt-del.service</filename> and execute
<filename>reboot.service</filename>. <command>systemd</command> 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.</para>
<para>Along with a unit file <filename>foo.service</filename>, the directory
<filename>foo.service.wants/</filename> may exist. All unit files symlinked from such a
directory are implicitly added as dependencies of type <varname>Wants=</varname> 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 <varname>Wants=</varname>, see below. The
preferred way to create symlinks in the <filename>.wants/</filename> directory of a unit file is
with the <command>enable</command> command of the
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
tool which reads information from the [Install] section of unit files (see below). A similar
functionality exists for <varname>Requires=</varname> type dependencies as well, the directory
suffix is <filename>.requires/</filename> in this case.</para>
<filename>foo.service.wants/</filename> may exist. All unit files symlinked from such a directory are
implicitly added as dependencies of type <varname>Wants=</varname> to the unit. Similar functionality
exists for <varname>Requires=</varname> type dependencies as well, the directory suffix is
<filename>.requires/</filename> 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
<varname>Wants=</varname>, see below. The preferred way to create symlinks in the
<filename>.wants/</filename> or <filename>.requires/</filename> 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 <command>enable</command> or <command>preset</command> commands of
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
<para>Along with a unit file <filename>foo.service</filename>, a "drop-in" directory
<filename>foo.service.d/</filename> may exist. All files with the suffix <literal>.conf</literal> from this