picnoir/Systemd
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

man: rework the description of Aliases and .wants/.requires directories

Browse source 
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
1 changed files with 32 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

58
man/systemd.unit.xml
View file

@ -123,34 +123,40 @@
do not need the prefix. Applications may use this to include do not need the prefix. Applications may use this to include
additional information in the unit files.</para> additional information in the unit files.</para>
<para>Units can be aliased (have an alternative name), by creating a symlink from the new name <para>Units can be aliased (have an alternative name), by creating a symlink from the new name to the
to the existing name in one of the unit search paths. For example, existing name in one of the unit search paths. For example, <filename>systemd-networkd.service</filename>
<filename>systemd-networkd.service</filename> has the alias has the alias <filename>dbus-org.freedesktop.network1.service</filename>, created during installation as
<filename>dbus-org.freedesktop.network1.service</filename>, created during installation as the a symlink, so when <command>systemd</command> is asked through D-Bus to load
symlink <filename>/usr/lib/systemd/system/dbus-org.freedesktop.network1.service</filename>. In <filename>dbus-org.freedesktop.network1.service</filename>, it'll load
addition, unit files may specify aliases through the <varname>Alias=</varname> directive in the <filename>systemd-networkd.service</filename>. Alias names may be used in commands like
[Install] section; those aliases are only effective when the unit is enabled. When the unit is <command>enable</command>, <command>disable</command>, <command>start</command>, <command>stop</command>,
enabled, symlinks will be created for those names, and removed when the unit is disabled. For <command>status</command>, and similar, and in all unit dependency directives, including
example, <filename>reboot.target</filename> specifies <varname>Wants=</varname>, <varname>Requires=</varname>, <varname>Before=</varname>,
<varname>Alias=ctrl-alt-del.target</varname>, so when enabled it will be invoked whenever <varname>After=</varname>. Aliases cannot be used with the <command>preset</command> command.</para>
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>, <para>Unit files may specify aliases through the <varname>Alias=</varname> directive in the [Install]
<command>status</command>, …, and in unit dependency directives <varname>Wants=</varname>, section. When the unit is enabled, symlinks will be created for those names, and removed when the unit is
<varname>Requires=</varname>, <varname>Before=</varname>, <varname>After=</varname>, …, with the disabled. For example, <filename>reboot.target</filename> specifies
limitation that aliases specified through <varname>Alias=</varname> are only effective when the <varname>Alias=ctrl-alt-del.target</varname>, so when enabled, the symlink
unit is enabled. Aliases cannot be used with the <command>preset</command> command.</para> <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 <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 <filename>foo.service.wants/</filename> may exist. All unit files symlinked from such a directory are
directory are implicitly added as dependencies of type <varname>Wants=</varname> to the unit. implicitly added as dependencies of type <varname>Wants=</varname> to the unit. Similar functionality
This is useful to hook units into the start-up of other units, without having to modify their exists for <varname>Requires=</varname> type dependencies as well, the directory suffix is
unit files. For details about the semantics of <varname>Wants=</varname>, see below. The <filename>.requires/</filename> in this case. This functionality is useful to hook units into the
preferred way to create symlinks in the <filename>.wants/</filename> directory of a unit file is start-up of other units, without having to modify their unit files. For details about the semantics of
with the <command>enable</command> command of the <varname>Wants=</varname>, see below. The preferred way to create symlinks in the
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> <filename>.wants/</filename> or <filename>.requires/</filename> directory of a unit file is by embedding
tool which reads information from the [Install] section of unit files (see below). A similar the dependency in [Install] section of the target unit, and creating the symlink in the file system with
functionality exists for <varname>Requires=</varname> type dependencies as well, the directory the with the <command>enable</command> or <command>preset</command> commands of
suffix is <filename>.requires/</filename> in this case.</para> <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
<para>Along with a unit file <filename>foo.service</filename>, a "drop-in" directory <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 <filename>foo.service.d/</filename> may exist. All files with the suffix <literal>.conf</literal> from this