mirror of
https://github.com/systemd/systemd-stable.git
synced 2025-03-06 12:58:22 +03:00
man: split systemd.special(7) into separate system/user sections
User units were in the middle, which is just confusing. Let's discuss all system units first, and all user units second. I'm using "System manager units" and "user manager units" instead of the more obvious "system units" and "user units", because there are also units like "user@.service".
This commit is contained in:
Zbigniew Jędrzejewski-Szmek
parent
a7edb403e5
commit
96719f158a
@ -104,15 +104,18 @@
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Units managed by the system's service manager</title>
|
||||
|
||||
<refsect2>
|
||||
<title>Special System Units</title>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><filename>-.mount</filename></term>
|
||||
<listitem>
|
||||
<para>The root mount point, i.e. the mount unit for the <filename>/</filename> path. This unit is
|
||||
unconditionally active, during the entire time the system is up, as this mount point is where the basic
|
||||
userspace is running from.</para>
|
||||
<para>The root mount point, i.e. the mount unit for the <filename>/</filename>
|
||||
path. This unit is unconditionally active, during the entire time the system is up, as
|
||||
this mount point is where the basic userspace is running from.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
@ -199,22 +202,23 @@
|
||||
<varlistentry>
|
||||
<term><filename>emergency.target</filename></term>
|
||||
<listitem>
|
||||
<para>A special target unit that starts an emergency shell on the main console. This target does not pull in
|
||||
any services or mounts. It is the most minimal version of starting the system in order to acquire an
|
||||
interactive shell; the only processes running are usually just the system manager (PID 1) and the shell
|
||||
process. This unit is supposed to be used with the kernel command line option
|
||||
<varname>systemd.unit=</varname>; it is also used when a file system check on a required file system fails,
|
||||
and boot-up cannot continue. Compare with <filename>rescue.target</filename>, which serves a similar purpose,
|
||||
but also starts the most basic services and mounts all file systems.</para>
|
||||
<para>A special target unit that starts an emergency shell on the main console. This
|
||||
target does not pull in any services or mounts. It is the most minimal version of
|
||||
starting the system in order to acquire an interactive shell; the only processes running
|
||||
are usually just the system manager (PID 1) and the shell process. This unit is supposed
|
||||
to be used with the kernel command line option <varname>systemd.unit=</varname>; it is
|
||||
also used when a file system check on a required file system fails, and boot-up cannot
|
||||
continue. Compare with <filename>rescue.target</filename>, which serves a similar
|
||||
purpose, but also starts the most basic services and mounts all file systems.</para>
|
||||
|
||||
<para>Use the <literal>systemd.unit=emergency.target</literal> kernel command line option to boot into this
|
||||
mode. A short alias for this kernel command line option is <literal>emergency</literal>, for compatibility
|
||||
with SysV.</para>
|
||||
<para>Use the <literal>systemd.unit=emergency.target</literal> kernel command line
|
||||
option to boot into this mode. A short alias for this kernel command line option is
|
||||
<literal>emergency</literal>, for compatibility with SysV.</para>
|
||||
|
||||
<para>In many ways booting into <filename>emergency.target</filename> is similar to the effect of booting
|
||||
with <literal>init=/bin/sh</literal> on the kernel command line, except that emergency mode provides you with
|
||||
the full system and service manager, and allows starting individual units in order to continue the boot
|
||||
process in steps.</para>
|
||||
<para>In many ways booting into <filename>emergency.target</filename> is similar to the
|
||||
effect of booting with <literal>init=/bin/sh</literal> on the kernel command line,
|
||||
except that emergency mode provides you with the full system and service manager, and
|
||||
allows starting individual units in order to continue the boot process in steps.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
@ -312,8 +316,8 @@
|
||||
<varlistentry>
|
||||
<term><filename>init.scope</filename></term>
|
||||
<listitem>
|
||||
<para>This scope unit is where the system and service manager (PID 1) itself resides. It is active as long as
|
||||
the system is running.</para>
|
||||
<para>This scope unit is where the system and service manager (PID 1) itself resides. It
|
||||
is active as long as the system is running.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
@ -443,13 +447,14 @@
|
||||
functionality to other hosts generally do not need to pull
|
||||
this in.</para>
|
||||
|
||||
<para>systemd automatically adds dependencies of type <varname>Wants=</varname> and <varname>After=</varname>
|
||||
for this target unit to all SysV init script service units with an LSB header referring to the
|
||||
<literal>$network</literal> facility.</para>
|
||||
<para>systemd automatically adds dependencies of type <varname>Wants=</varname> and
|
||||
<varname>After=</varname> for this target unit to all SysV init script service units
|
||||
with an LSB header referring to the <literal>$network</literal> facility.</para>
|
||||
|
||||
<para>Note that this unit is only useful during the original system start-up logic. After the system has
|
||||
completed booting up, it will not track the online state of the system anymore. Due to this it cannot be used
|
||||
as a network connection monitor concept, it is purely a one-time system start-up concept.</para>
|
||||
<para>Note that this unit is only useful during the original system start-up
|
||||
logic. After the system has completed booting up, it will not track the online state of
|
||||
the system anymore. Due to this it cannot be used as a network connection monitor
|
||||
concept, it is purely a one-time system start-up concept.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
@ -524,19 +529,20 @@
|
||||
<varlistentry>
|
||||
<term><filename>rescue.target</filename></term>
|
||||
<listitem>
|
||||
<para>A special target unit that pulls in the base system (including system mounts) and spawns a rescue
|
||||
shell. Isolate to this target in order to administer the system in single-user mode with all file systems
|
||||
mounted but with no services running, except for the most basic. Compare with
|
||||
<filename>emergency.target</filename>, which is much more reduced and does not provide the file systems or
|
||||
most basic services. Compare with <filename>multi-user.target</filename>, this target could be seen as
|
||||
<para>A special target unit that pulls in the base system (including system mounts) and
|
||||
spawns a rescue shell. Isolate to this target in order to administer the system in
|
||||
single-user mode with all file systems mounted but with no services running, except for
|
||||
the most basic. Compare with <filename>emergency.target</filename>, which is much more
|
||||
reduced and does not provide the file systems or most basic services. Compare with
|
||||
<filename>multi-user.target</filename>, this target could be seen as
|
||||
<filename>single-user.target</filename>.</para>
|
||||
|
||||
<para><filename>runlevel1.target</filename> is an alias for this target unit, for compatibility with
|
||||
SysV.</para>
|
||||
<para><filename>runlevel1.target</filename> is an alias for this target unit, for
|
||||
compatibility with SysV.</para>
|
||||
|
||||
<para>Use the <literal>systemd.unit=rescue.target</literal> kernel command line option to boot into this
|
||||
mode. A short alias for this kernel command line option is <literal>1</literal>, for compatibility with
|
||||
SysV.</para>
|
||||
<para>Use the <literal>systemd.unit=rescue.target</literal> kernel command line option
|
||||
to boot into this mode. A short alias for this kernel command line option is
|
||||
<literal>1</literal>, for compatibility with SysV.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
@ -589,13 +595,15 @@
|
||||
<term><filename>slices.target</filename></term>
|
||||
<listitem>
|
||||
<para>A special target unit that sets up all slice units (see
|
||||
<citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
|
||||
details) that shall be active after boot. By default the generic <filename>system.slice</filename>
|
||||
slice unit, as well as the root slice unit <filename>-.slice</filename>, is pulled in and ordered before
|
||||
this unit (see below).</para>
|
||||
<citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
|
||||
for details) that shall be active after boot. By default the generic
|
||||
<filename>system.slice</filename> slice unit, as well as the root slice unit
|
||||
<filename>-.slice</filename>, is pulled in and ordered before this unit (see
|
||||
below).</para>
|
||||
|
||||
<para>It's a good idea to add <varname>WantedBy=slices.target</varname> lines to the <literal>[Install]</literal>
|
||||
section of all slices units that may be installed dynamically.</para>
|
||||
<para>It's a good idea to add <varname>WantedBy=slices.target</varname> lines to the
|
||||
<literal>[Install]</literal> section of all slices units that may be installed
|
||||
dynamically.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
@ -669,13 +677,16 @@
|
||||
<citerefentry><refentrytitle>systemd.offline-updates</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
|
||||
</para>
|
||||
|
||||
<para>Updates should happen before the <filename>system-update.target</filename> is reached, and the services
|
||||
which implement them should cause the machine to reboot. The main units executing the update should order
|
||||
themselves after <filename>system-update-pre.target</filename> but not pull it in. Services which want to run
|
||||
during system updates only, but before the actual system update is executed should order themselves before
|
||||
this unit and pull it in. As a safety measure, if this does not happen, and
|
||||
<filename>/system-update</filename> still exists after <filename>system-update.target</filename> is reached,
|
||||
<filename>system-update-cleanup.service</filename> will remove this symlink and reboot the machine.</para>
|
||||
<para>Updates should happen before the <filename>system-update.target</filename> is
|
||||
reached, and the services which implement them should cause the machine to reboot. The
|
||||
main units executing the update should order themselves after
|
||||
<filename>system-update-pre.target</filename> but not pull it in. Services which want to
|
||||
run during system updates only, but before the actual system update is executed should
|
||||
order themselves before this unit and pull it in. As a safety measure, if this does not
|
||||
happen, and <filename>/system-update</filename> still exists after
|
||||
<filename>system-update.target</filename> is reached,
|
||||
<filename>system-update-cleanup.service</filename> will remove this symlink and reboot
|
||||
the machine.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
@ -708,9 +719,9 @@
|
||||
</varlistentry>
|
||||
|
||||
</variablelist>
|
||||
</refsect1>
|
||||
</refsect2>
|
||||
|
||||
<refsect1>
|
||||
<refsect2>
|
||||
<title>Special System Units for Devices</title>
|
||||
|
||||
<para>Some target units are automatically pulled in as devices of
|
||||
@ -763,9 +774,9 @@
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect1>
|
||||
</refsect2>
|
||||
|
||||
<refsect1>
|
||||
<refsect2>
|
||||
<title>Special Passive System Units </title>
|
||||
|
||||
<para>A number of special system targets are defined that can be
|
||||
@ -855,24 +866,27 @@
|
||||
<varlistentry>
|
||||
<term><filename>nss-lookup.target</filename></term>
|
||||
<listitem>
|
||||
<para>A target that should be used as synchronization point for all host/network name service lookups. Note
|
||||
that this is independent of UNIX user/group name lookups for which <filename>nss-user-lookup.target</filename>
|
||||
should be used. All services for which the availability of full host/network name resolution is essential
|
||||
should be ordered after this target, but not pull it in. systemd automatically adds dependencies of type
|
||||
<varname>After=</varname> for this target unit to all SysV init script service units with an LSB header
|
||||
referring to the <literal>$named</literal> facility.</para>
|
||||
<para>A target that should be used as synchronization point for all host/network name
|
||||
service lookups. Note that this is independent of UNIX user/group name lookups for which
|
||||
<filename>nss-user-lookup.target</filename> should be used. All services for which the
|
||||
availability of full host/network name resolution is essential should be ordered after
|
||||
this target, but not pull it in. systemd automatically adds dependencies of type
|
||||
<varname>After=</varname> for this target unit to all SysV init script service units
|
||||
with an LSB header referring to the <literal>$named</literal> facility.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
<term><filename>nss-user-lookup.target</filename></term>
|
||||
<listitem>
|
||||
<para>A target that should be used as synchronization point for all regular UNIX user/group name service
|
||||
lookups. Note that this is independent of host/network name lookups for which
|
||||
<filename>nss-lookup.target</filename> should be used. All services for which the availability of the full
|
||||
user/group database is essential should be ordered after this target, but not pull it in. All services which
|
||||
provide parts of the user/group database should be ordered before this target, and pull it in. Note that this
|
||||
unit is only relevant for regular users and groups — system users and groups are required to be resolvable
|
||||
during earliest boot already, and hence do not need any special ordering against this target.</para>
|
||||
<para>A target that should be used as synchronization point for all regular UNIX
|
||||
user/group name service lookups. Note that this is independent of host/network name
|
||||
lookups for which <filename>nss-lookup.target</filename> should be used. All services
|
||||
for which the availability of the full user/group database is essential should be
|
||||
ordered after this target, but not pull it in. All services which provide parts of the
|
||||
user/group database should be ordered before this target, and pull it in. Note that this
|
||||
unit is only relevant for regular users and groups — system users and groups are
|
||||
required to be resolvable during earliest boot already, and hence do not need any
|
||||
special ordering against this target.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
<varlistentry>
|
||||
@ -917,98 +931,22 @@
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect1>
|
||||
</refsect2>
|
||||
|
||||
<refsect1>
|
||||
<title>Special User Units</title>
|
||||
|
||||
<para>When systemd runs as a user instance, the following special
|
||||
units are available, which have similar definitions as their
|
||||
system counterparts:
|
||||
<filename>exit.target</filename>,
|
||||
<filename>default.target</filename>,
|
||||
<filename>shutdown.target</filename>,
|
||||
<filename>sockets.target</filename>,
|
||||
<filename>timers.target</filename>,
|
||||
<filename>paths.target</filename>,
|
||||
<filename>bluetooth.target</filename>,
|
||||
<filename>printer.target</filename>,
|
||||
<filename>smartcard.target</filename>,
|
||||
<filename>sound.target</filename>.</para>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Special Passive User Units</title>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><filename>graphical-session.target</filename></term>
|
||||
<listitem>
|
||||
<para>This target is active whenever any graphical session is running. It is used to stop user services which
|
||||
only apply to a graphical (X, Wayland, etc.) session when the session is terminated. Such services should
|
||||
have <literal>PartOf=graphical-session.target</literal> in their <literal>[Unit]</literal> section. A target
|
||||
for a particular session (e. g. <filename>gnome-session.target</filename>) starts and stops
|
||||
<literal>graphical-session.target</literal> with <literal>BindsTo=graphical-session.target</literal>.</para>
|
||||
|
||||
<para>Which services are started by a session target is determined by the <literal>Wants=</literal> and
|
||||
<literal>Requires=</literal> dependencies. For services that can be enabled independently, symlinks in
|
||||
<literal>.wants/</literal> and <literal>.requires/</literal> should be used, see
|
||||
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>. Those
|
||||
symlinks should either be shipped in packages, or should be added dynamically after installation, for example
|
||||
using <literal>systemctl add-wants</literal>, see
|
||||
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
|
||||
</para>
|
||||
|
||||
<example>
|
||||
<title>Nautilus as part of a GNOME session</title>
|
||||
|
||||
<para><literal>gnome-session.target</literal> pulls in Nautilus as top-level service:</para>
|
||||
|
||||
<programlisting>[Unit]
|
||||
Description=User systemd services for GNOME graphical session
|
||||
Wants=nautilus.service
|
||||
BindsTo=graphical-session.target</programlisting>
|
||||
|
||||
<para><literal>nautilus.service</literal> gets stopped when the session stops:</para>
|
||||
|
||||
<programlisting>[Unit]
|
||||
Description=Render the desktop icons with Nautilus
|
||||
PartOf=graphical-session.target
|
||||
|
||||
[Service]
|
||||
…</programlisting>
|
||||
</example>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><filename>graphical-session-pre.target</filename></term>
|
||||
<listitem>
|
||||
<para>This target contains services which set up the environment or global configuration of a graphical
|
||||
session, such as SSH/GPG agents (which need to export an environment variable into all desktop processes) or
|
||||
migration of obsolete d-conf keys after an OS upgrade (which needs to happen before starting any process that
|
||||
might use them). This target must be started before starting a graphical session like
|
||||
<filename>gnome-session.target</filename>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<refsect2>
|
||||
<title>Special Slice Units</title>
|
||||
|
||||
<para>There are four <literal>.slice</literal> units which form the basis of the hierarchy for assignment of
|
||||
resources for services, users, and virtual machines or containers. See
|
||||
<citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details about slice
|
||||
units.</para>
|
||||
<para>There are four <literal>.slice</literal> units which form the basis of the hierarchy for
|
||||
assignment of resources for services, users, and virtual machines or containers. See
|
||||
<citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>7</manvolnum></citerefentry>
|
||||
for details about slice units.</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><filename>-.slice</filename></term>
|
||||
<listitem>
|
||||
<para>The root slice is the root of the slice hierarchy. It usually does not contain units directly, but may
|
||||
be used to set defaults for the whole tree.</para>
|
||||
<para>The root slice is the root of the slice hierarchy. It usually does not contain
|
||||
units directly, but may be used to set defaults for the whole tree.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
@ -1040,6 +978,91 @@ PartOf=graphical-session.target
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
<title>Units managed by the user's service manager</title>
|
||||
|
||||
<refsect2>
|
||||
<title>Special User Units</title>
|
||||
|
||||
<para>When systemd runs as a user instance, the following special
|
||||
units are available, which have similar definitions as their
|
||||
system counterparts:
|
||||
<filename>exit.target</filename>,
|
||||
<filename>default.target</filename>,
|
||||
<filename>shutdown.target</filename>,
|
||||
<filename>sockets.target</filename>,
|
||||
<filename>timers.target</filename>,
|
||||
<filename>paths.target</filename>,
|
||||
<filename>bluetooth.target</filename>,
|
||||
<filename>printer.target</filename>,
|
||||
<filename>smartcard.target</filename>,
|
||||
<filename>sound.target</filename>.</para>
|
||||
</refsect2>
|
||||
|
||||
<refsect2>
|
||||
<title>Special Passive User Units</title>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><filename>graphical-session.target</filename></term>
|
||||
<listitem>
|
||||
<para>This target is active whenever any graphical session is running. It is used to
|
||||
stop user services which only apply to a graphical (X, Wayland, etc.) session when the
|
||||
session is terminated. Such services should have
|
||||
<literal>PartOf=graphical-session.target</literal> in their <literal>[Unit]</literal>
|
||||
section. A target for a particular session (e. g.
|
||||
<filename>gnome-session.target</filename>) starts and stops
|
||||
<literal>graphical-session.target</literal> with
|
||||
<literal>BindsTo=graphical-session.target</literal>.</para>
|
||||
|
||||
<para>Which services are started by a session target is determined by the
|
||||
<literal>Wants=</literal> and <literal>Requires=</literal> dependencies. For services
|
||||
that can be enabled independently, symlinks in <literal>.wants/</literal> and
|
||||
<literal>.requires/</literal> should be used, see
|
||||
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
|
||||
Those symlinks should either be shipped in packages, or should be added dynamically
|
||||
after installation, for example using <literal>systemctl add-wants</literal>, see
|
||||
<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
|
||||
</para>
|
||||
|
||||
<example>
|
||||
<title>Nautilus as part of a GNOME session</title>
|
||||
|
||||
<para><literal>gnome-session.target</literal> pulls in Nautilus as top-level service:</para>
|
||||
|
||||
<programlisting>[Unit]
|
||||
Description=User systemd services for GNOME graphical session
|
||||
Wants=nautilus.service
|
||||
BindsTo=graphical-session.target</programlisting>
|
||||
|
||||
<para><literal>nautilus.service</literal> gets stopped when the session stops:</para>
|
||||
|
||||
<programlisting>[Unit]
|
||||
Description=Render the desktop icons with Nautilus
|
||||
PartOf=graphical-session.target
|
||||
|
||||
[Service]
|
||||
…</programlisting>
|
||||
</example>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><filename>graphical-session-pre.target</filename></term>
|
||||
<listitem>
|
||||
<para>This target contains services which set up the environment or global configuration
|
||||
of a graphical session, such as SSH/GPG agents (which need to export an environment
|
||||
variable into all desktop processes) or migration of obsolete d-conf keys after an OS
|
||||
upgrade (which needs to happen before starting any process that might use them). This
|
||||
target must be started before starting a graphical session like
|
||||
<filename>gnome-session.target</filename>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user