HALF ECHO LEARN / REFERENCE COLLECTION
v262.2man/systemd.special.xml
Git blob: eafea18529a77343401004cfbfb6050ec395b22b
Lines 1001–1623 of 1,623
</varlistentry>
<varlistentry>
<term><filename>tpm2.target</filename></term>
<listitem>
<para>This target is started automatically if a TPM2 device is discovered, either by the OS or by
the firmware. It acts as synchronization point for services that require TPM2 device access. The
target unit is enqueued by
<citerefentry><refentrytitle>systemd-tpm2-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
if it detects that the firmware has discovered a TPM2 device but the OS kernel has not activated
a driver for it yet. It is also pulled in whenever
<citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
discovers a TPM2 device. The target unit is ordered after the <filename>/dev/tpmrm0</filename>
device node, so that it only becomes active once the TPM2 device is actually accessible. Early
boot programs that intend to access the TPM2 device should hence order themselves after this
target unit, but not pull it in.</para>
<xi:include href="version-info.xml" xpointer="v256"/>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Special Passive System Units </title>
<para>A number of special system targets are defined that can be
used to properly order boot-up of optional services. These targets
are generally not part of the initial boot transaction, unless
they are explicitly pulled in by one of the implementing services.
Note specifically that these <emphasis>passive</emphasis> target
units are generally not pulled in by the consumer of a service,
but by the provider of the service. This means: a consuming
service should order itself after these targets (as appropriate),
but not pull it in. A providing service should order itself before
these targets (as appropriate) and pull it in (via a
<varname>Wants=</varname> type dependency).</para>
<para>Note that these passive units cannot be started manually,
i.e. <literal>systemctl start time-sync.target</literal> will fail
with an error. They can only be pulled in by dependency. This is
enforced since they exist for ordering purposes only and thus are
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>8</manvolnum></citerefentry>/
<citerefentry><refentrytitle>systemd-veritysetup@.service</refentrytitle><manvolnum>8</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 index="false">blockdev@dev-mapper-foobar.target</filename> for the storage device
<filename index="false">/dev/mapper/foobar</filename>.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<varlistentry>
<term><filename>cryptsetup-pre.target</filename></term>
<listitem>
<para>This passive target unit may be pulled in by services
that want to run before any encrypted block device is set
up. All encrypted block devices are set up after this target
has been reached. Since the shutdown order is implicitly the
reverse start-up order between units, this target is
particularly useful to ensure that a service is shut down
only after all encrypted block devices are fully
stopped.</para>
<xi:include href="version-info.xml" xpointer="v215"/>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>veritysetup-pre.target</filename></term>
<listitem>
<para>This passive target unit may be pulled in by services
that want to run before any verity integrity protected block
device is set up. All verity integrity protected block
devices are set up after this target has been reached. Since
the shutdown order is implicitly the reverse start-up order
between units, this target is particularly useful to ensure
that a service is shut down only after all verity integrity
protected block devices are fully stopped.</para>
<xi:include href="version-info.xml" xpointer="v248"/>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>first-boot-complete.target</filename></term>
<listitem>
<para>This passive target is intended as a synchronization point for units that need to run once
during the first boot. Only after all units ordered before this target have finished, will the
<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
be committed to disk, marking the first boot as completed. If the boot is aborted at any time
before that, the next boot will re-run any units with <varname>ConditionFirstBoot=yes</varname>.
</para>
<xi:include href="version-info.xml" xpointer="v247"/>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>getty-pre.target</filename></term>
<listitem>
<para>A special passive target unit. Users of this target
are expected to pull it in the boot transaction via
a dependency (e.g. <varname>Wants=</varname>). Order your
unit before this unit if you want to make use of the console
just before <filename>getty</filename> is started.
</para>
<xi:include href="version-info.xml" xpointer="v235"/>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>imports-pre.target</filename></term>
<listitem>
<para>A passive unit that is ordered before all disk image download jobs to execute on system
boot. This is used by
<citerefentry><refentrytitle>systemd-import-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
<xi:include href="version-info.xml" xpointer="v258"/>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>local-fs-pre.target</filename></term>
<listitem>
<para>This target unit is
automatically ordered before
all local mount points marked
with <option>auto</option>
(see above). It can be used to
execute certain units before
all local mounts.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>network.target</filename></term>
<listitem>
<para>This unit is supposed to indicate when network functionality is available, but it is only
very weakly defined what that is supposed to mean. However, the following should apply at
minimum:</para>
<itemizedlist>
<listitem><para>At start-up, any configured synthetic network devices (i.e. not physical ones
that require hardware to show up and be probed, but virtual ones like bridge devices and
similar which are created programmatically) that do not depend on any underlying hardware
should be allocated by the time this target is reached. It is not necessary for these
interfaces to also have completed IP level configuration by the time
<filename>network.target</filename> is reached.</para></listitem>
<listitem><para>At shutdown, a unit that is ordered after <filename>network.target</filename>
will be stopped before the network — to whatever level it might be set up by then — is shut
down. It is hence useful when writing service files that require network access on shutdown,
which should order themselves after this target, but not pull it in. Also see <ulink
url="https://systemd.io/NETWORK_ONLINE">Running Services After the Network Is Up</ulink> for
more information.</para></listitem>
</itemizedlist>
<para>It must emphasized that at start-up there's no guarantee that hardware-based devices have
shown up by the time this target is reached, or even acquired complete IP configuration. For that
purpose use <filename>network-online.target</filename> as described above.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>network-pre.target</filename></term>
<listitem>
<para>This passive target unit may be pulled in by services that want to run before any network
is set up, for example for the purpose of setting up a firewall. All network management software
orders itself after this target, but does not pull it in. Also see <ulink
url="https://systemd.io/NETWORK_ONLINE">Running Services After the Network Is Up</ulink> for more
information.</para>
<xi:include href="version-info.xml" xpointer="v214"/>
</listitem>
</varlistentry>
<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.</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>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>remote-fs-pre.target</filename></term>
<listitem>
<para>This target unit is automatically ordered before all
mount point units (see above) and cryptsetup/veritysetup devices
marked with the <option>_netdev</option>. It can be used to run
certain units before remote encrypted devices and mounts are established.
Note that this unit is generally not part of the initial
transaction, unless the unit that wants to be ordered before
all remote mounts pulls it in via a
<varname>Wants=</varname> type dependency. If the unit wants
to be pulled in by the first remote mount showing up, it
should use <filename>network-online.target</filename> (see
above).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>rpcbind.target</filename></term>
<listitem>
<para>The portmapper/rpcbind pulls in this target and orders
itself before it, to indicate its availability.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>ssh-access.target</filename></term>
<listitem>
<para>Service and socket units that provide remote SSH secure shell access to the local system
should pull in this unit and order themselves before this unit. It's supposed to act as a
milestone indicating if and when SSH access into the system is available. It should only become
active when an SSH port is bound for remote clients (i.e. if SSH is used as a local privilege
escalation mechanism, it should <emphasis>not</emphasis> involve this target unit), regardless of
the protocol choices, i.e. regardless of whether IPv4, IPv6 or <constant>AF_VSOCK</constant> is
used.</para>
<xi:include href="version-info.xml" xpointer="v256"/>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>time-set.target</filename></term>
<listitem>
<para>Services responsible for setting the system clock (<constant>CLOCK_REALTIME</constant>)
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, roughly monotonic
time is desired should be ordered after this unit, but not pull it in.</para>
<para>This target does not provide the accuracy guarantees of
<filename>time-sync.target</filename> (see below), however does not depend on remote clock
sources to be reachable, i.e. the target is typically not delayed by network problems and
similar. Use of this target is recommended for services where approximate clock accuracy and
rough monotonicity is desired but activation shall not be delayed for possibly unreliable network
communication.</para>
<para>The service manager automatically adds dependencies of type <varname>After=</varname> for
this target unit to all timer units with at least one <varname>OnCalendar=</varname>
directive.</para>
<para>The
<citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
service is a simple daemon that pulls in this target and orders itself before it. Besides
implementing the SNTP network protocol it maintains a timestamp file on disk whose modification
time is regularly updated. At service start-up the local system clock is set from that modification time,
ensuring it increases roughly monotonically.</para>
<para>Note that ordering a unit after <filename>time-set.target</filename> only has effect if
there's actually a service ordered before it that delays it until the clock is adjusted for rough
monotonicity. Otherwise, this target might get reached before the clock is adjusted to be roughly
monotonic. Enable
<citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
or an alternative NTP implementation to delay the target.</para>
<xi:include href="version-info.xml" xpointer="v242"/>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>time-sync.target</filename></term>
<listitem>
<para>Services indicating completed synchronization of the system clock
(<constant>CLOCK_REALTIME</constant>) to a remote source should pull in this target and order
themselves before it. Services where accurate time is essential should be ordered after this
unit, but not pull it in.</para>
<para>The service manager automatically adds dependencies of type <varname>After=</varname> for
this target unit to all timer units with at least one <varname>OnCalendar=</varname> directive.</para>
<para>This target provides stricter clock accuracy guarantees than
<filename>time-set.target</filename> (see above), but likely requires
network communication and thus introduces unpredictable delays.
Services that require clock accuracy and where network
communication delays are acceptable should use this target. Services that require a less accurate
clock, and only approximate and roughly monotonic clock behaviour should use
<filename>time-set.target</filename> instead.</para>
<para>Note that ordering a unit after <filename>time-sync.target</filename> only has effect if
there's actually a service ordered before it that delays it until clock synchronization is
reached. Otherwise, this target might get reached before the clock is synchronized to any remote
accurate reference clock. When using
<citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
enable
<citerefentry><refentrytitle>systemd-time-wait-sync.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
to delay the target; or use an equivalent service for other NTP implementations.</para>
<table>
<title>Comparison</title>
<tgroup cols='2' align='left' colsep='1' rowsep='1'>
<colspec colname="time-set" />
<colspec colname="time-sync" />
<thead>
<row>
<entry><filename>time-set.target</filename></entry>
<entry><filename>time-sync.target</filename></entry>
</row>
</thead>
<tbody>
<row>
<entry>"quick" to reach</entry>
<entry>"slow" to reach</entry>
</row>
<row>
<entry>typically uses local clock sources, boot process not affected by availability of external resources</entry>
<entry>typically uses remote clock sources, inserts dependencies on remote resources into boot process</entry>
</row>
<row>
<entry>reliable, because local</entry>
<entry>unreliable, because typically network involved</entry>
</row>
<row>
<entry>typically guarantees an approximate and roughly monotonic clock only</entry>
<entry>typically guarantees an accurate clock</entry>
</row>
<row>
<entry>implemented by <filename>systemd-timesyncd.service</filename></entry>
<entry>implemented by <filename>systemd-time-wait-sync.service</filename></entry>
</row>
</tbody>
</tgroup>
</table>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<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>5</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>
<xi:include href="version-info.xml" xpointer="v206"/>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>machine.slice</filename></term>
<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>
<xi:include href="version-info.xml" xpointer="v206"/>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>capsule.slice</filename></term>
<listitem>
<para>By default, all capsules encapsulated in <filename>capsule@.service</filename> are found in
this slice.</para>
<xi:include href="version-info.xml" xpointer="v255"/>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>system.slice</filename></term>
<listitem>
<para>By default, all system services started by <command>systemd</command> are found in this
slice.</para>
<xi:include href="version-info.xml" xpointer="v206"/>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>user.slice</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>
<xi:include href="version-info.xml" xpointer="v206"/>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<refsect1>
<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:</para>
<variablelist>
<varlistentry>
<term><filename>default.target</filename></term>
<listitem>
<para>This is the main target of the user service manager, started by default when the service
manager is invoked. 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>
<xi:include href="version-info.xml" xpointer="v242"/>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
<term><filename>capsule@.target</filename></term>
<listitem>
<para>This is the main target of capsule service managers, started by default, instantiated with
the capsule name. This may be used to define different sets of units that are started for
different capsules via generic unit definitions. For details about capsules see
<citerefentry><refentrytitle>capsule@.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
<xi:include href="version-info.xml" xpointer="v255"/>
</listitem>
</varlistentry>
</variablelist>
<para>In addition, the following units are available which have definitions similar to their
system counterparts:
<filename>exit.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 [Unit]
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>
<xi:include href="version-info.xml" xpointer="v234"/>
</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>
<xi:include href="version-info.xml" xpointer="v234"/>
</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
<filename>xdg-desktop-autostart.target</filename>.</para>
<xi:include href="version-info.xml" xpointer="v246"/>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>Special User Slice Units</title>
<para>There are four <literal>.slice</literal> units which form the basis of the user hierarchy for
assignment of resources for user applications and services. See
<citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details about slice units and the documentation about
<ulink url="https://systemd.io/DESKTOP_ENVIRONMENTS">Desktop Environments</ulink>
for further information.</para>
<variablelist>
<varlistentry>
<term><filename>-.slice</filename></term>
<listitem>
<para>The root slice is the root of the user's slice hierarchy.
It usually does not contain units directly, but may be used to set defaults for the whole tree.</para>
<xi:include href="version-info.xml" xpointer="v247"/>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>app.slice</filename></term>
<listitem>
<para>By default, all user services and applications managed by
<command>systemd</command> are found in this slice.
All interactively launched applications like web browsers and text editors
as well as non-critical services should be placed into this slice.</para>
<xi:include href="version-info.xml" xpointer="v247"/>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>session.slice</filename></term>
<listitem>
<para>All essential services and applications required for the
session should use this slice.
These are services that either cannot be restarted easily
or where latency issues may affect the interactivity of the system and applications.
This includes the display server, screen readers and other services such as DBus or XDG portals.
Such services should be configured to be part of this slice by
adding <varname>Slice=session.slice</varname> to their unit files.</para>
<xi:include href="version-info.xml" xpointer="v247"/>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>background.slice</filename></term>
<listitem>
<para>All services running low-priority background tasks should use this slice.
This permits resources to be preferentially assigned to the other slices.
Examples include non-interactive tasks like file indexing or backup operations
where latency is not important.</para>
<xi:include href="version-info.xml" xpointer="v247"/>
</listitem>
</varlistentry>
</variablelist>
</refsect2>
</refsect1>
<refsect1>
<title>See Also</title>
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>user@.service</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
</simplelist></para>
</refsect1>
</refentry>