<?xml version='1.0'?> <!--*-nxml-*-->
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-
-<!--
- SPDX-License-Identifier: LGPL-2.1+
--->
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="systemd.special">
<filename>cryptsetup-pre.target</filename>,
<filename>cryptsetup.target</filename>,
<filename>ctrl-alt-del.target</filename>,
+ <filename>blockdev@.target</filename>,
<filename>boot-complete.target</filename>,
<filename>default.target</filename>,
<filename>emergency.target</filename>,
<filename>hibernate.target</filename>,
<filename>hybrid-sleep.target</filename>,
<filename>suspend-then-hibernate.target</filename>,
+ <filename>initrd.target</filename>,
<filename>initrd-fs.target</filename>,
<filename>initrd-root-device.target</filename>,
<filename>initrd-root-fs.target</filename>,
<filename>sysinit.target</filename>,
<filename>system-update.target</filename>,
<filename>system-update-pre.target</filename>,
+ <filename>time-set.target</filename>,
<filename>time-sync.target</filename>,
<filename>timers.target</filename>,
<filename>umount.target</filename>,
</refsect1>
<refsect1>
- <title>Units managed by the system's service manager</title>
+ <title>Units managed by the system service manager</title>
<refsect2>
<title>Special System Units</title>
<varlistentry>
<term><filename>default.target</filename></term>
<listitem>
- <para>The default unit systemd starts at bootup. Usually,
- this should be aliased (symlinked) to
- <filename>multi-user.target</filename> or
- <filename>graphical.target</filename>.</para>
+ <para>The default unit systemd starts at bootup. Usually, this should be aliased (symlinked) to
+ <filename>multi-user.target</filename> or <filename>graphical.target</filename>. See
+ <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+ more discussion.</para>
- <para>The default unit systemd starts at bootup can be
- overridden with the <varname>systemd.unit=</varname> kernel
- command line option.</para>
+ <para>The default unit systemd starts at bootup can be overridden with the
+ <varname>systemd.unit=</varname> kernel command line option, or more conveniently, with the short
+ names like <varname>single</varname>, <varname>rescue</varname>, <varname>1</varname>,
+ <varname>3</varname>, <varname>5</varname>, …; see
+ <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
</listitem>
</varlistentry>
<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
+ target does not pull in other 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
+ are usually just the system manager (PID 1) and the shell process. This unit may be used
+ by specifying <varname>emergency</varname> on the kernel command line; 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>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>Note that depending on how <filename>emergency.target</filename> is reached, the root file
+ system might be mounted read-only or read-write (no remounting is done specially for this
+ target). For example, the system may boot with root mounted read-only when <varname>ro</varname>
+ is used on the kernel command line and remain this way for <filename>emergency.target</filename>,
+ or the system may transition to <filename>emergency.target</filename> after the system has been
+ partially booted and disks have already been remounted read-write.</para>
</listitem>
</varlistentry>
<varlistentry>
this unit (or <filename>multi-user.target</filename>) during
installation. This is best configured via
<varname>WantedBy=graphical.target</varname> in the unit's
- <literal>[Install]</literal> section.</para>
+ [Install] section.</para>
</listitem>
</varlistentry>
<varlistentry>
is active as long as the system is running.</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><filename>initrd.target</filename></term>
+ <listitem>
+ <para>This is the default target in the initramfs, similar to <filename>default.target</filename>
+ in the main system. It is used to mount the real root and transition to it. See
+ <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
+ more discussion.</para>
+ </listitem>
+ </varlistentry>
<varlistentry>
<term><filename>initrd-fs.target</filename></term>
<listitem>
add <varname>Wants=</varname> dependencies for their unit to
this unit during installation. This is best configured via
<varname>WantedBy=multi-user.target</varname> in the unit's
- <literal>[Install]</literal> section.</para>
+ [Install] section.</para>
</listitem>
</varlistentry>
<varlistentry>
applications get pulled in via <varname>Wants=</varname>
dependencies from this unit. This is best configured via a
<varname>WantedBy=paths.target</varname> in the path unit's
- <literal>[Install]</literal> section.</para>
+ [Install] section.</para>
</listitem>
</varlistentry>
<varlistentry>
<para>Adding slice units to <filename>slices.target</filename> is generally not
necessary. Instead, when some unit that uses <varname>Slice=</varname> is started, the
specified slice will be started automatically. Adding
- <varname>WantedBy=slices.target</varname> lines to the <literal>[Install]</literal>
+ <varname>WantedBy=slices.target</varname> lines to the [Install]
section should only be done for units that need to be always active. In that case care
needs to be taken to avoid creating a loop through the automatic dependencies on
"parent" slices.</para>
<varname>Wants=</varname> dependencies to this unit for
their socket unit during installation. This is best
configured via a <varname>WantedBy=sockets.target</varname>
- in the socket unit's <literal>[Install]</literal>
+ in the socket unit's [Install]
section.</para>
</listitem>
</varlistentry>
applications get pulled in via <varname>Wants=</varname>
dependencies from this unit. This is best configured via
<varname>WantedBy=timers.target</varname> in the timer
- unit's <literal>[Install]</literal> section.</para>
+ unit's [Install] section.</para>
</listitem>
</varlistentry>
<varlistentry>
not useful as only unit within a transaction.</para>
<variablelist>
+ <varlistentry>
+ <term><filename>blockdev@.target</filename></term>
+ <listitem><para>This template unit is used to order mount units and other consumers of block
+ devices after services that synthesize these block devices. In particular, this is intended to be
+ used with storage services (such as
+ <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>)
+ that allocate and manage a virtual block device. Storage services are ordered before an instance of
+ <filename>blockdev@.target</filename>, and the consumer units after it. The ordering is
+ particularly relevant during shutdown, as it ensures that the mount is deactivated first and the
+ service backing the mount later. The <filename>blockdev@.target</filename> instance should be
+ pulled in via a <option>Wants=</option> dependency of the storage daemon and thus generally not be
+ part of any transaction unless a storage daemon is used. The instance name for instances of this
+ template unit must be a properly escaped block device node path, e.g.
+ <filename>blockdev@dev-mapper-foobar.target</filename> for the storage device
+ <filename>/dev/mapper/foobar</filename>.</para></listitem>
+ </varlistentry>
<varlistentry>
<term><filename>cryptsetup-pre.target</filename></term>
<listitem>
the <literal>$portmap</literal> facility.</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><filename>time-set.target</filename></term>
+ <listitem>
+ <para>Services responsible for setting the system clock from
+ a local source (such as a maintained timestamp file or
+ imprecise real-time clock) should pull in this target and
+ order themselves before it. Services where approximate time
+ is desired should be ordered after this unit, but not pull
+ it in. This target does not provide the accuracy guarantees
+ of <filename>time-sync.target</filename>.</para>
+ </listitem>
+ </varlistentry>
<varlistentry>
<term><filename>time-sync.target</filename></term>
<listitem>
<para>By default, all user processes and services started on
behalf of the user, including the per-user systemd instance
are found in this slice. This is pulled in by
- <filename>systemd-logind.service</filename></para>
+ <filename>systemd-logind.service</filename>.</para>
</listitem>
</varlistentry>
<listitem>
<para>By default, all virtual machines and containers
registered with <command>systemd-machined</command> are
- found in this slice. This is pulled in by
- <filename>systemd-machined.service</filename></para>
+ found in this slice. This is pulled in by
+ <filename>systemd-machined.service</filename>.</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
- <title>Units managed by the user's service manager</title>
+ <title>Units managed by the user 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
+ units are available:</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><filename>default.target</filename></term>
+ <listitem>
+ <para>This is the main target of the user session, started by default. Various services that
+ compose the normal user session should be pulled into this target. In this regard,
+ <filename>default.target</filename> is similar to <filename>multi-user.target</filename> in the
+ system instance, but it is a real unit, not an alias.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>In addition, the following units are available which have definitions similar to their
system counterparts:
<filename>exit.target</filename>,
- <filename>default.target</filename>,
<filename>shutdown.target</filename>,
<filename>sockets.target</filename>,
<filename>timers.target</filename>,
<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>
+ <literal>PartOf=graphical-session.target</literal> in their [Unit]
section. A target for a particular session (e. g.
<filename>gnome-session.target</filename>) starts and stops
<literal>graphical-session.target</literal> with
<filename>gnome-session.target</filename>.</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><filename>xdg-desktop-autostart.target</filename></term>
+ <listitem>
+ <para>The XDG specification defines a way to autostart applications using XDG desktop files.
+ systemd ships
+ <citerefentry><refentrytitle>systemd-xdg-autostart-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+ for the XDG desktop files in autostart directories.
+ Desktop Environments can opt-in to use this service by adding a <varname>Wants=</varname>
+ dependency on <literal>xdg-desktop-autostart.target</literal></para>.
+ </listitem>
+ </varlistentry>
</variablelist>
</refsect2>
</refsect1>
projects / thirdparty / systemd.git / blobdiff