]> git.ipfire.org Git - thirdparty/systemd.git/blob - man/systemd.special.xml
Merge pull request #23088 from yuwata/udev-event-blocker
[thirdparty/systemd.git] / man / systemd.special.xml
1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
5
6 <refentry id="systemd.special">
7
8 <refentryinfo>
9 <title>systemd.special</title>
10 <productname>systemd</productname>
11 </refentryinfo>
12
13 <refmeta>
14 <refentrytitle>systemd.special</refentrytitle>
15 <manvolnum>7</manvolnum>
16 </refmeta>
17
18 <refnamediv>
19 <refname>systemd.special</refname>
20 <refpurpose>Special systemd units</refpurpose>
21 </refnamediv>
22
23 <refsynopsisdiv><para>
24 <!-- sort alphabetically, targets first --><filename>basic.target</filename>,
25 <filename>bluetooth.target</filename>,
26 <filename>cryptsetup-pre.target</filename>,
27 <filename>cryptsetup.target</filename>,
28 <filename>veritysetup-pre.target</filename>,
29 <filename>veritysetup.target</filename>,
30 <filename>ctrl-alt-del.target</filename>,
31 <filename>blockdev@.target</filename>,
32 <filename>boot-complete.target</filename>,
33 <filename>default.target</filename>,
34 <filename>emergency.target</filename>,
35 <filename>exit.target</filename>,
36 <filename>factory-reset.target</filename>,
37 <filename>final.target</filename>,
38 <filename>first-boot-complete.target</filename>,
39 <filename>getty.target</filename>,
40 <filename>getty-pre.target</filename>,
41 <filename>graphical.target</filename>,
42 <filename>halt.target</filename>,
43 <filename>hibernate.target</filename>,
44 <filename>hybrid-sleep.target</filename>,
45 <filename>suspend-then-hibernate.target</filename>,
46 <filename>initrd.target</filename>,
47 <filename>initrd-fs.target</filename>,
48 <filename>initrd-root-device.target</filename>,
49 <filename>initrd-root-fs.target</filename>,
50 <filename>initrd-usr-fs.target</filename>,
51 <filename>integritysetup-pre.target</filename>,
52 <filename>integritysetup.target</filename>,
53 <filename>kbrequest.target</filename>,
54 <filename>kexec.target</filename>,
55 <filename>local-fs-pre.target</filename>,
56 <filename>local-fs.target</filename>,
57 <filename>machines.target</filename>
58 <filename>multi-user.target</filename>,
59 <filename>network-online.target</filename>,
60 <filename>network-pre.target</filename>,
61 <filename>network.target</filename>,
62 <filename>nss-lookup.target</filename>,
63 <filename>nss-user-lookup.target</filename>,
64 <filename>paths.target</filename>,
65 <filename>poweroff.target</filename>,
66 <filename>printer.target</filename>,
67 <filename>reboot.target</filename>,
68 <filename>remote-cryptsetup.target</filename>,
69 <filename>remote-veritysetup.target</filename>,
70 <filename>remote-fs-pre.target</filename>,
71 <filename>remote-fs.target</filename>,
72 <filename>rescue.target</filename>,
73 <filename>rpcbind.target</filename>,
74 <filename>runlevel2.target</filename>,
75 <filename>runlevel3.target</filename>,
76 <filename>runlevel4.target</filename>,
77 <filename>runlevel5.target</filename>,
78 <filename>shutdown.target</filename>,
79 <filename>sigpwr.target</filename>,
80 <filename>sleep.target</filename>,
81 <filename>slices.target</filename>,
82 <filename>smartcard.target</filename>,
83 <filename>sockets.target</filename>,
84 <filename>sound.target</filename>,
85 <filename>suspend.target</filename>,
86 <filename>swap.target</filename>,
87 <filename>sysinit.target</filename>,
88 <filename>system-update.target</filename>,
89 <filename>system-update-pre.target</filename>,
90 <filename>time-set.target</filename>,
91 <filename>time-sync.target</filename>,
92 <filename>timers.target</filename>,
93 <filename>umount.target</filename>,
94 <filename>usb-gadget.target</filename>,
95 <!-- slices --><filename>-.slice</filename>,
96 <filename>system.slice</filename>,
97 <filename>user.slice</filename>,
98 <filename>machine.slice</filename>,
99 <!-- the rest --><filename>-.mount</filename>,
100 <filename>dbus.service</filename>,
101 <filename>dbus.socket</filename>,
102 <filename>display-manager.service</filename>,
103 <filename>init.scope</filename>,
104 <filename>syslog.socket</filename>,
105 <filename>system-update-cleanup.service</filename>
106 </para></refsynopsisdiv>
107
108 <refsect1>
109 <title>Description</title>
110
111 <para>A few units are treated specially by systemd. Many of them have
112 special internal semantics and cannot be renamed, while others simply
113 have a standard meaning and should be present on all systems.</para>
114 </refsect1>
115
116 <refsect1>
117 <title>Units managed by the system service manager</title>
118
119 <refsect2>
120 <title>Special System Units</title>
121
122 <variablelist>
123 <varlistentry>
124 <term><filename>-.mount</filename></term>
125 <listitem>
126 <para>The root mount point, i.e. the mount unit for the <filename>/</filename>
127 path. This unit is unconditionally active, during the entire time the system is up, as
128 this mount point is where the basic userspace is running from.</para>
129 </listitem>
130 </varlistentry>
131
132 <varlistentry>
133 <term><filename>basic.target</filename></term>
134 <listitem>
135 <para>A special target unit covering basic boot-up.</para>
136
137 <para>systemd automatically adds dependency of the type
138 <varname>After=</varname> for this target unit to all
139 services (except for those with
140 <varname>DefaultDependencies=no</varname>).</para>
141
142 <para>Usually, this should pull-in all local mount points plus
143 <filename>/var/</filename>, <filename>/tmp/</filename> and
144 <filename>/var/tmp/</filename>, swap devices, sockets, timers,
145 path units and other basic initialization necessary for general
146 purpose daemons. The mentioned mount points are special cased
147 to allow them to be remote.
148 </para>
149
150 <para>This target usually does not pull in any non-target units
151 directly, but rather does so indirectly via other early boot targets.
152 It is instead meant as a synchronization point for late boot
153 services. Refer to
154 <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>
155 for details on the targets involved.
156 </para>
157 </listitem>
158 </varlistentry>
159 <varlistentry>
160 <term><filename>boot-complete.target</filename></term>
161 <listitem>
162 <para>This target is intended as generic synchronization point for services that shall determine or act on
163 whether the boot process completed successfully. Order units that are required to succeed for a boot process
164 to be considered successful before this unit, and add a <varname>Requires=</varname> dependency from the
165 target unit to them. Order units that shall only run when the boot process is considered successful after the
166 target unit and pull in the target from it, also with <varname>Requires=</varname>. Note that by default this
167 target unit is not part of the initial boot transaction, but is supposed to be pulled in only if required by
168 units that want to run only on successful boots.</para>
169
170 <para>See
171 <citerefentry><refentrytitle>systemd-boot-check-no-failures.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
172 for a service that implements a generic system health check and orders itself before
173 <filename>boot-complete.target</filename>.</para>
174
175 <para>See
176 <citerefentry><refentrytitle>systemd-bless-boot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
177 for a service that propagates boot success information to the boot loader, and orders itself after
178 <filename>boot-complete.target</filename>.</para>
179 </listitem>
180 </varlistentry>
181 <varlistentry>
182 <term><filename>ctrl-alt-del.target</filename></term>
183 <listitem>
184 <para>systemd starts this target whenever Control+Alt+Del is
185 pressed on the console. Usually, this should be aliased
186 (symlinked) to <filename>reboot.target</filename>.</para>
187 </listitem>
188 </varlistentry>
189 <varlistentry>
190 <term><filename>cryptsetup.target</filename></term>
191 <listitem>
192 <para>A target that pulls in setup services for all
193 encrypted block devices.</para>
194 </listitem>
195 </varlistentry>
196 <varlistentry>
197 <term><filename>veritysetup.target</filename></term>
198 <listitem>
199 <para>A target that pulls in setup services for all
200 verity integrity protected block devices.</para>
201 </listitem>
202 </varlistentry>
203 <varlistentry>
204 <term><filename>dbus.service</filename></term>
205 <listitem>
206 <para>A special unit for the D-Bus bus daemon. As soon as
207 this service is fully started up systemd will connect to it
208 and register its service.</para>
209 </listitem>
210 </varlistentry>
211 <varlistentry>
212 <term><filename>dbus.socket</filename></term>
213 <listitem>
214 <para>A special unit for the D-Bus system bus socket. All
215 units with <varname>Type=dbus</varname> automatically gain a
216 dependency on this unit.</para>
217 </listitem>
218 </varlistentry>
219 <varlistentry>
220 <term><filename>default.target</filename></term>
221 <listitem>
222 <para>The default unit systemd starts at bootup. Usually, this should be aliased (symlinked) to
223 <filename>multi-user.target</filename> or <filename>graphical.target</filename>. See
224 <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
225 more discussion.</para>
226
227 <para>The default unit systemd starts at bootup can be overridden with the
228 <varname>systemd.unit=</varname> kernel command line option, or more conveniently, with the short
229 names like <varname>single</varname>, <varname>rescue</varname>, <varname>1</varname>,
230 <varname>3</varname>, <varname>5</varname>, …; see
231 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
232 </listitem>
233 </varlistentry>
234 <varlistentry>
235 <term><filename>display-manager.service</filename></term>
236 <listitem>
237 <para>The display manager service. Usually, this should be
238 aliased (symlinked) to <filename>gdm.service</filename> or a
239 similar display manager service.</para>
240 </listitem>
241 </varlistentry>
242 <varlistentry>
243 <term><filename>emergency.target</filename></term>
244 <listitem>
245 <para>A special target unit that starts an emergency shell on the main console. This
246 target does not pull in other services or mounts. It is the most minimal version of
247 starting the system in order to acquire an interactive shell; the only processes running
248 are usually just the system manager (PID 1) and the shell process. This unit may be used
249 by specifying <varname>emergency</varname> on the kernel command line; it is
250 also used when a file system check on a required file system fails and boot-up cannot
251 continue. Compare with <filename>rescue.target</filename>, which serves a similar
252 purpose, but also starts the most basic services and mounts all file systems.</para>
253
254 <para>In many ways booting into <filename>emergency.target</filename> is similar to the
255 effect of booting with <literal>init=/bin/sh</literal> on the kernel command line,
256 except that emergency mode provides you with the full system and service manager, and
257 allows starting individual units in order to continue the boot process in steps.</para>
258
259 <para>Note that depending on how <filename>emergency.target</filename> is reached, the root file
260 system might be mounted read-only or read-write (no remounting is done specially for this
261 target). For example, the system may boot with root mounted read-only when <varname>ro</varname>
262 is used on the kernel command line and remain this way for <filename>emergency.target</filename>,
263 or the system may transition to <filename>emergency.target</filename> after the system has been
264 partially booted and disks have already been remounted read-write.</para>
265 </listitem>
266 </varlistentry>
267 <varlistentry>
268 <term><filename>exit.target</filename></term>
269 <listitem>
270 <para>A special service unit for shutting down the system or
271 user service manager. It is equivalent to
272 <filename>poweroff.target</filename> on non-container
273 systems, and also works in containers.</para>
274
275 <para>systemd will start this unit when it receives the
276 <constant>SIGTERM</constant> or <constant>SIGINT</constant>
277 signal when running as user service daemon.</para>
278
279 <para>Normally, this (indirectly) pulls in
280 <filename>shutdown.target</filename>, which in turn should be
281 conflicted by all units that want to be scheduled for
282 shutdown when the service manager starts to exit.</para>
283 </listitem>
284 </varlistentry>
285 <varlistentry>
286 <term><filename>factory-reset.target</filename></term>
287 <listitem>
288 <para>A special target to trigger a factory reset.</para>
289 </listitem>
290 </varlistentry>
291 <varlistentry>
292 <term><filename>final.target</filename></term>
293 <listitem>
294 <para>A special target unit that is used during the shutdown
295 logic and may be used to pull in late services after all
296 normal services are already terminated and all mounts
297 unmounted.
298 </para>
299 </listitem>
300 </varlistentry>
301 <varlistentry>
302 <term><filename>getty.target</filename></term>
303 <listitem>
304 <para>A special target unit that pulls in statically
305 configured local TTY <filename>getty</filename> instances.
306 </para>
307 </listitem>
308 </varlistentry>
309 <varlistentry>
310 <term><filename>graphical.target</filename></term>
311 <listitem>
312 <para>A special target unit for setting up a graphical login
313 screen. This pulls in
314 <filename>multi-user.target</filename>.</para>
315
316 <para>Units that are needed for graphical logins shall add
317 <varname>Wants=</varname> dependencies for their unit to
318 this unit (or <filename>multi-user.target</filename>) during
319 installation. This is best configured via
320 <varname>WantedBy=graphical.target</varname> in the unit's
321 [Install] section.</para>
322 </listitem>
323 </varlistentry>
324 <varlistentry>
325 <term><filename>hibernate.target</filename></term>
326 <listitem>
327 <para>A special target unit for hibernating the system. This
328 pulls in <filename>sleep.target</filename>.</para>
329 </listitem>
330 </varlistentry>
331 <varlistentry>
332 <term><filename>hybrid-sleep.target</filename></term>
333 <listitem>
334 <para>A special target unit for hibernating and suspending
335 the system at the same time. This pulls in
336 <filename>sleep.target</filename>.</para>
337 </listitem>
338 </varlistentry>
339 <varlistentry>
340 <term><filename>suspend-then-hibernate.target</filename></term>
341 <listitem>
342 <para>A special target unit for suspending the system for a period
343 of time, waking it and putting it into hibernate. This pulls in
344 <filename>sleep.target</filename>.</para>
345 </listitem>
346 </varlistentry>
347
348 <varlistentry>
349 <term><filename>halt.target</filename></term>
350 <listitem>
351 <para>A special target unit for shutting down and halting
352 the system. Note that this target is distinct from
353 <filename>poweroff.target</filename> in that it generally
354 really just halts the system rather than powering it
355 down.</para>
356
357 <para>Applications wanting to halt the system should not start this unit
358 directly, but should instead execute <command>systemctl halt</command>
359 (possibly with the <option>--no-block</option> option) or call
360 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
361 <command>org.freedesktop.systemd1.Manager.Halt</command> D-Bus method
362 directly.</para>
363 </listitem>
364 </varlistentry>
365 <varlistentry>
366 <term><filename>init.scope</filename></term>
367 <listitem>
368 <para>This scope unit is where the system and service manager (PID 1) itself resides. It
369 is active as long as the system is running.</para>
370 </listitem>
371 </varlistentry>
372 <varlistentry>
373 <term><filename>initrd.target</filename></term>
374 <listitem>
375 <para>This is the default target in the initramfs, similar to <filename>default.target</filename>
376 in the main system. It is used to mount the real root and transition to it. See
377 <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry> for
378 more discussion.</para>
379 </listitem>
380 </varlistentry>
381 <varlistentry>
382 <term><filename>initrd-fs.target</filename></term>
383 <listitem>
384 <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry>
385 automatically adds dependencies of type <varname>Before=</varname> to
386 <filename>sysroot-usr.mount</filename> and all mount points found in
387 <filename>/etc/fstab</filename> that have the <option>x-initrd.mount</option> mount option set
388 and do not have the <option>noauto</option> mount option set. It is also indirectly ordered after
389 <filename>sysroot.mount</filename>. Thus, once this target is reached the
390 <filename>/sysroot/</filename> hierarchy is fully set up, in preparation for the transition to
391 the host OS.</para>
392 </listitem>
393 </varlistentry>
394 <varlistentry>
395 <term><filename>initrd-root-device.target</filename></term>
396 <listitem>
397 <para>A special initrd target unit that is reached when the root filesystem device is available, but before
398 it has been mounted.
399 <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry>
400 and
401 <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry>
402 automatically setup the appropriate dependencies to make this happen.
403 </para>
404 </listitem>
405 </varlistentry>
406 <varlistentry>
407 <term><filename>initrd-root-fs.target</filename></term>
408 <listitem>
409 <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry>
410 automatically adds dependencies of type <varname>Before=</varname> to the
411 <filename>sysroot.mount</filename> unit, which is generated from the kernel command line's
412 <varname>root=</varname> setting (or equivalent).</para>
413 </listitem>
414 </varlistentry>
415 <varlistentry>
416 <term><filename>initrd-usr-fs.target</filename></term>
417 <listitem>
418 <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry>
419 automatically adds dependencies of type <varname>Before=</varname> to the
420 <filename>sysusr-usr.mount</filename> unit, which is generated from the kernel command line's
421 <varname>usr=</varname> switch. Services may order themselves after this target unit in order to
422 run once the <filename>/sysusr/</filename> hierarchy becomes available, on systems that come up
423 initially without a root file system, but with an initialized <filename>/usr/</filename> and need
424 to access that before setting up the root file system to ultimately switch to. On systems where
425 <varname>usr=</varname> is not used this target is ordered after
426 <filename>sysroot.mount</filename> and thus mostly equivalent to
427 <filename>initrd-root-fs.target</filename>. In effect on any system once this target is reached
428 the file system backing <filename>/usr/</filename> is mounted, though possibly at two different
429 locations, either below the <filename>/sysusr/</filename> or the <filename>/sysroot/</filename>
430 hierarchies.</para>
431 </listitem>
432 </varlistentry>
433 <varlistentry>
434 <term><filename>kbrequest.target</filename></term>
435 <listitem>
436 <para>systemd starts this target whenever Alt+ArrowUp is
437 pressed on the console. Note that any user with physical access
438 to the machine will be able to do this, without authentication,
439 so this should be used carefully.</para>
440 </listitem>
441 </varlistentry>
442 <varlistentry>
443 <term><filename>kexec.target</filename></term>
444 <listitem>
445 <para>A special target unit for shutting down and rebooting
446 the system via kexec.</para>
447
448 <para>Applications wanting to reboot the system should not start this unit
449 directly, but should instead execute <command>systemctl kexec</command>
450 (possibly with the <option>--no-block</option> option) or call
451 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
452 <command>org.freedesktop.systemd1.Manager.KExec</command> D-Bus method
453 directly.</para>
454 </listitem>
455 </varlistentry>
456 <varlistentry>
457 <term><filename>local-fs.target</filename></term>
458 <listitem>
459 <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry>
460 automatically adds dependencies of type
461 <varname>Before=</varname> to all mount units that refer to
462 local mount points for this target unit. In addition, it
463 adds dependencies of type <varname>Wants=</varname> to this
464 target unit for those mounts listed in
465 <filename>/etc/fstab</filename> that have the
466 <option>auto</option> mount option set.</para>
467 </listitem>
468 </varlistentry>
469 <varlistentry>
470 <term><filename>machines.target</filename></term>
471 <listitem>
472 <para>A standard target unit for starting all the containers
473 and other virtual machines. See <filename>systemd-nspawn@.service</filename>
474 for an example.</para>
475 </listitem>
476 </varlistentry>
477 <varlistentry>
478 <term><filename>multi-user.target</filename></term>
479 <listitem>
480 <para>A special target unit for setting up a multi-user
481 system (non-graphical). This is pulled in by
482 <filename>graphical.target</filename>.</para>
483
484 <para>Units that are needed for a multi-user system shall
485 add <varname>Wants=</varname> dependencies for their unit to
486 this unit during installation. This is best configured via
487 <varname>WantedBy=multi-user.target</varname> in the unit's
488 [Install] section.</para>
489 </listitem>
490 </varlistentry>
491 <varlistentry>
492 <term><filename>network-online.target</filename></term>
493 <listitem>
494 <para>Units that strictly require a configured network
495 connection should pull in
496 <filename>network-online.target</filename> (via a
497 <varname>Wants=</varname> type dependency) and order
498 themselves after it. This target unit is intended to pull in
499 a service that delays further execution until the network is
500 sufficiently set up. What precisely this requires is left to
501 the implementation of the network managing service.</para>
502
503 <para>Note the distinction between this unit and
504 <filename>network.target</filename>. This unit is an active
505 unit (i.e. pulled in by the consumer rather than the
506 provider of this functionality) and pulls in a service which
507 possibly adds substantial delays to further execution. In
508 contrast, <filename>network.target</filename> is a passive
509 unit (i.e. pulled in by the provider of the functionality,
510 rather than the consumer) that usually does not delay
511 execution much. Usually, <filename>network.target</filename>
512 is part of the boot of most systems, while
513 <filename>network-online.target</filename> is not, except
514 when at least one unit requires it. Also see <ulink
515 url="https://systemd.io/NETWORK_ONLINE">Running
516 Services After the Network is up</ulink> for more
517 information.</para>
518
519 <para>All mount units for remote network file systems automatically pull in this unit, and order
520 themselves after it. Note that networking daemons that simply <emphasis>provide</emphasis>
521 functionality to other hosts (as opposed to <emphasis>consume</emphasis> functionality of other
522 hosts) generally do not need to pull this in.</para>
523
524 <para>systemd automatically adds dependencies of type <varname>Wants=</varname> and
525 <varname>After=</varname> for this target unit to all SysV init script service units
526 with an LSB header referring to the <literal>$network</literal> facility.</para>
527
528 <para>Note that this unit is only useful during the original system start-up
529 logic. After the system has completed booting up, it will not track the online state of
530 the system anymore. Due to this it cannot be used as a network connection monitor
531 concept, it is purely a one-time system start-up concept.</para>
532 </listitem>
533 </varlistentry>
534 <varlistentry>
535 <term><filename>paths.target</filename></term>
536 <listitem>
537 <para>A special target unit that sets up all path units (see
538 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>
539 for details) that shall be active after boot.</para>
540
541 <para>It is recommended that path units installed by
542 applications get pulled in via <varname>Wants=</varname>
543 dependencies from this unit. This is best configured via a
544 <varname>WantedBy=paths.target</varname> in the path unit's
545 [Install] section.</para>
546 </listitem>
547 </varlistentry>
548 <varlistentry>
549 <term><filename>poweroff.target</filename></term>
550 <listitem>
551 <para>A special target unit for shutting down and powering
552 off the system.</para>
553
554 <para>Applications wanting to power off the system should not start this unit
555 directly, but should instead execute <command>systemctl poweroff</command>
556 (possibly with the <option>--no-block</option> option) or call
557 <citerefentry><refentrytitle>systemd-logind</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
558 <command>org.freedesktop.login1.Manager.PowerOff</command> D-Bus method
559 directly.</para>
560
561 <para><filename>runlevel0.target</filename> is an alias for
562 this target unit, for compatibility with SysV.</para>
563 </listitem>
564 </varlistentry>
565 <varlistentry>
566 <term><filename>reboot.target</filename></term>
567 <listitem>
568 <para>A special target unit for shutting down and rebooting
569 the system.</para>
570
571 <para>Applications wanting to reboot the system should not start this unit
572 directly, but should instead execute <command>systemctl reboot</command>
573 (possibly with the <option>--no-block</option> option) or call
574 <citerefentry><refentrytitle>systemd-logind</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
575 <command>org.freedesktop.login1.Manager.Reboot</command> D-Bus method
576 directly.</para>
577
578 <para><filename>runlevel6.target</filename> is an alias for
579 this target unit, for compatibility with SysV.</para>
580 </listitem>
581 </varlistentry>
582 <varlistentry>
583 <term><filename>remote-cryptsetup.target</filename></term>
584 <listitem>
585 <para>Similar to <filename>cryptsetup.target</filename>, but for encrypted
586 devices which are accessed over the network. It is used for
587 <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>8</manvolnum></citerefentry>
588 entries marked with <option>_netdev</option>.</para>
589 </listitem>
590 </varlistentry>
591 <varlistentry>
592 <term><filename>remote-veritysetup.target</filename></term>
593 <listitem>
594 <para>Similar to <filename>veritysetup.target</filename>, but for verity
595 integrity protected devices which are accessed over the network. It is used for
596 <citerefentry><refentrytitle>veritytab</refentrytitle><manvolnum>8</manvolnum></citerefentry>
597 entries marked with <option>_netdev</option>.</para>
598 </listitem>
599 </varlistentry>
600 <varlistentry>
601 <term><filename>remote-fs.target</filename></term>
602 <listitem>
603 <para>Similar to <filename>local-fs.target</filename>, but
604 for remote mount points.</para>
605
606 <para>systemd automatically adds dependencies of type
607 <varname>After=</varname> for this target unit to all SysV
608 init script service units with an LSB header referring to
609 the <literal>$remote_fs</literal> facility.</para>
610 </listitem>
611 </varlistentry>
612 <varlistentry>
613 <term><filename>rescue.target</filename></term>
614 <listitem>
615 <para>A special target unit that pulls in the base system (including system mounts) and
616 spawns a rescue shell. Isolate to this target in order to administer the system in
617 single-user mode with all file systems mounted but with no services running, except for
618 the most basic. Compare with <filename>emergency.target</filename>, which is much more
619 reduced and does not provide the file systems or most basic services. Compare with
620 <filename>multi-user.target</filename>, this target could be seen as
621 <filename>single-user.target</filename>.</para>
622
623 <para><filename>runlevel1.target</filename> is an alias for this target unit, for
624 compatibility with SysV.</para>
625
626 <para>Use the <literal>systemd.unit=rescue.target</literal> kernel command line option
627 to boot into this mode. A short alias for this kernel command line option is
628 <literal>1</literal>, for compatibility with SysV.</para>
629 </listitem>
630 </varlistentry>
631 <varlistentry>
632 <term><filename>runlevel2.target</filename></term>
633 <term><filename>runlevel3.target</filename></term>
634 <term><filename>runlevel4.target</filename></term>
635 <term><filename>runlevel5.target</filename></term>
636 <listitem>
637 <para>These are targets that are called whenever the SysV
638 compatibility code asks for runlevel 2, 3, 4, 5,
639 respectively. It is a good idea to make this an alias for
640 (i.e. symlink to) <filename>graphical.target</filename>
641 (for runlevel 5) or <filename>multi-user.target</filename>
642 (the others).</para>
643 </listitem>
644 </varlistentry>
645 <varlistentry>
646 <term><filename>shutdown.target</filename></term>
647 <listitem>
648 <para>A special target unit that terminates the services on
649 system shutdown.</para>
650
651 <para>Services that shall be terminated on system shutdown
652 shall add <varname>Conflicts=</varname> and
653 <varname>Before=</varname> dependencies to this unit for
654 their service unit, which is implicitly done when
655 <varname>DefaultDependencies=yes</varname> is set (the
656 default).</para>
657 </listitem>
658 </varlistentry>
659 <varlistentry>
660 <term><filename>sigpwr.target</filename></term>
661 <listitem>
662 <para>A special target that is started when systemd receives
663 the SIGPWR process signal, which is normally sent by the
664 kernel or UPS daemons when power fails.</para>
665 </listitem>
666 </varlistentry>
667 <varlistentry>
668 <term><filename>sleep.target</filename></term>
669 <listitem>
670 <para>A special target unit that is pulled in by
671 <filename>suspend.target</filename>,
672 <filename>hibernate.target</filename> and
673 <filename>hybrid-sleep.target</filename> and may be used to
674 hook units into the sleep state logic.</para>
675 </listitem>
676 </varlistentry>
677 <varlistentry>
678 <term><filename>slices.target</filename></term>
679 <listitem>
680 <para>A special target unit that sets up all slice units (see
681 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
682 for details) that shall always be active after boot. By default the generic
683 <filename>system.slice</filename> slice unit as well as the root slice unit
684 <filename>-.slice</filename> are pulled in and ordered before this unit (see
685 below).</para>
686
687 <para>Adding slice units to <filename>slices.target</filename> is generally not
688 necessary. Instead, when some unit that uses <varname>Slice=</varname> is started, the
689 specified slice will be started automatically. Adding
690 <varname>WantedBy=slices.target</varname> lines to the [Install]
691 section should only be done for units that need to be always active. In that case care
692 needs to be taken to avoid creating a loop through the automatic dependencies on
693 "parent" slices.</para>
694 </listitem>
695 </varlistentry>
696 <varlistentry>
697 <term><filename>sockets.target</filename></term>
698 <listitem>
699 <para>A special target unit that sets up all socket
700 units (see
701 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
702 for details) that shall be active after boot.</para>
703
704 <para>Services that can be socket-activated shall add
705 <varname>Wants=</varname> dependencies to this unit for
706 their socket unit during installation. This is best
707 configured via a <varname>WantedBy=sockets.target</varname>
708 in the socket unit's [Install]
709 section.</para>
710 </listitem>
711 </varlistentry>
712 <varlistentry>
713 <term><filename>suspend.target</filename></term>
714 <listitem>
715 <para>A special target unit for suspending the system. This
716 pulls in <filename>sleep.target</filename>.</para>
717 </listitem>
718 </varlistentry>
719 <varlistentry>
720 <term><filename>swap.target</filename></term>
721 <listitem>
722 <para>Similar to <filename>local-fs.target</filename>, but
723 for swap partitions and swap files.</para>
724 </listitem>
725 </varlistentry>
726 <varlistentry>
727 <term><filename>sysinit.target</filename></term>
728 <listitem>
729 <para>systemd automatically adds dependencies of the types
730 <varname>Requires=</varname> and <varname>After=</varname>
731 for this target unit to all services (except for those with
732 <varname>DefaultDependencies=no</varname>).</para>
733
734 <para>This target pulls in the services required for system
735 initialization. System services pulled in by this target should
736 declare <varname>DefaultDependencies=no</varname> and specify
737 all their dependencies manually, including access to anything
738 more than a read only root filesystem. For details on the
739 dependencies of this target, refer to
740 <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
741 </para>
742 </listitem>
743 </varlistentry>
744 <varlistentry>
745 <term><filename>syslog.socket</filename></term>
746 <listitem>
747 <para>The socket unit syslog implementations should listen
748 on. All userspace log messages will be made available on
749 this socket. For more information about syslog integration,
750 please consult the <ulink
751 url="https://www.freedesktop.org/wiki/Software/systemd/syslog">Syslog
752 Interface</ulink> document.</para>
753 </listitem>
754 </varlistentry>
755 <varlistentry>
756 <term><filename>system-update.target</filename></term>
757 <term><filename>system-update-pre.target</filename></term>
758 <term><filename>system-update-cleanup.service</filename></term>
759 <listitem>
760 <para>A special target unit that is used for offline system updates.
761 <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
762 will redirect the boot process to this target if <filename>/system-update</filename>
763 exists. For more information see
764 <citerefentry><refentrytitle>systemd.offline-updates</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
765 </para>
766
767 <para>Updates should happen before the <filename>system-update.target</filename> is
768 reached, and the services which implement them should cause the machine to reboot. The
769 main units executing the update should order themselves after
770 <filename>system-update-pre.target</filename> but not pull it in. Services which want to
771 run during system updates only, but before the actual system update is executed should
772 order themselves before this unit and pull it in. As a safety measure, if this does not
773 happen, and <filename>/system-update</filename> still exists after
774 <filename>system-update.target</filename> is reached,
775 <filename>system-update-cleanup.service</filename> will remove this symlink and reboot
776 the machine.</para>
777 </listitem>
778 </varlistentry>
779 <varlistentry>
780 <term><filename>timers.target</filename></term>
781 <listitem>
782 <para>A special target unit that sets up all timer units
783 (see
784 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>
785 for details) that shall be active after boot.</para>
786
787 <para>It is recommended that timer units installed by
788 applications get pulled in via <varname>Wants=</varname>
789 dependencies from this unit. This is best configured via
790 <varname>WantedBy=timers.target</varname> in the timer
791 unit's [Install] section.</para>
792 </listitem>
793 </varlistentry>
794 <varlistentry>
795 <term><filename>umount.target</filename></term>
796 <listitem>
797 <para>A special target unit that unmounts all mount and
798 automount points on system shutdown.</para>
799
800 <para>Mounts that shall be unmounted on system shutdown
801 shall add Conflicts dependencies to this unit for their
802 mount unit, which is implicitly done when
803 <varname>DefaultDependencies=yes</varname> is set (the
804 default).</para>
805 </listitem>
806 </varlistentry>
807
808 </variablelist>
809 </refsect2>
810
811 <refsect2>
812 <title>Special System Units for Devices</title>
813
814 <para>Some target units are automatically pulled in as devices of
815 certain kinds show up in the system. These may be used to
816 automatically activate various services based on the specific type
817 of the available hardware.</para>
818
819 <variablelist>
820 <varlistentry>
821 <term><filename>bluetooth.target</filename></term>
822 <listitem>
823 <para>This target is started automatically as soon as a
824 Bluetooth controller is plugged in or becomes available at
825 boot.</para>
826
827 <para>This may be used to pull in Bluetooth management
828 daemons dynamically when Bluetooth hardware is found.</para>
829 </listitem>
830 </varlistentry>
831 <varlistentry>
832 <term><filename>printer.target</filename></term>
833 <listitem>
834 <para>This target is started automatically as soon as a
835 printer is plugged in or becomes available at boot.</para>
836
837 <para>This may be used to pull in printer management daemons
838 dynamically when printer hardware is found.</para>
839 </listitem>
840 </varlistentry>
841 <varlistentry>
842 <term><filename>smartcard.target</filename></term>
843 <listitem>
844 <para>This target is started automatically as soon as a
845 smartcard controller is plugged in or becomes available at
846 boot.</para>
847
848 <para>This may be used to pull in smartcard management
849 daemons dynamically when smartcard hardware is found.</para>
850 </listitem>
851 </varlistentry>
852 <varlistentry>
853 <term><filename>sound.target</filename></term>
854 <listitem>
855 <para>This target is started automatically as soon as a
856 sound card is plugged in or becomes available at
857 boot.</para>
858
859 <para>This may be used to pull in audio management daemons
860 dynamically when audio hardware is found.</para>
861 </listitem>
862 </varlistentry>
863 <varlistentry>
864 <term><filename>usb-gadget.target</filename></term>
865 <listitem>
866 <para>This target is started automatically as soon as a
867 USB Device Controller becomes available at boot.</para>
868
869 <para>This may be used to pull in usb gadget
870 dynamically when UDC hardware is found.</para>
871 </listitem>
872 </varlistentry>
873 </variablelist>
874 </refsect2>
875
876 <refsect2>
877 <title>Special Passive System Units </title>
878
879 <para>A number of special system targets are defined that can be
880 used to properly order boot-up of optional services. These targets
881 are generally not part of the initial boot transaction, unless
882 they are explicitly pulled in by one of the implementing services.
883 Note specifically that these <emphasis>passive</emphasis> target
884 units are generally not pulled in by the consumer of a service,
885 but by the provider of the service. This means: a consuming
886 service should order itself after these targets (as appropriate),
887 but not pull it in. A providing service should order itself before
888 these targets (as appropriate) and pull it in (via a
889 <varname>Wants=</varname> type dependency).</para>
890
891 <para>Note that these passive units cannot be started manually,
892 i.e. <literal>systemctl start time-sync.target</literal> will fail
893 with an error. They can only be pulled in by dependency. This is
894 enforced since they exist for ordering purposes only and thus are
895 not useful as only unit within a transaction.</para>
896
897 <variablelist>
898 <varlistentry>
899 <term><filename>blockdev@.target</filename></term>
900 <listitem><para>This template unit is used to order mount units and other consumers of block
901 devices after services that synthesize these block devices. In particular, this is intended to be
902 used with storage services (such as
903 <citerefentry><refentrytitle>systemd-cryptsetup@.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>/
904 <citerefentry><refentrytitle>systemd-veritysetup@.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>)
905 that allocate and manage a virtual block device. Storage services are ordered before an instance of
906 <filename>blockdev@.target</filename>, and the consumer units after it. The ordering is
907 particularly relevant during shutdown, as it ensures that the mount is deactivated first and the
908 service backing the mount later. The <filename>blockdev@.target</filename> instance should be
909 pulled in via a <option>Wants=</option> dependency of the storage daemon and thus generally not be
910 part of any transaction unless a storage daemon is used. The instance name for instances of this
911 template unit must be a properly escaped block device node path, e.g.
912 <filename index="false">blockdev@dev-mapper-foobar.target</filename> for the storage device
913 <filename index="false">/dev/mapper/foobar</filename>.</para></listitem>
914 </varlistentry>
915 <varlistentry>
916 <term><filename>cryptsetup-pre.target</filename></term>
917 <listitem>
918 <para>This passive target unit may be pulled in by services
919 that want to run before any encrypted block device is set
920 up. All encrypted block devices are set up after this target
921 has been reached. Since the shutdown order is implicitly the
922 reverse start-up order between units, this target is
923 particularly useful to ensure that a service is shut down
924 only after all encrypted block devices are fully
925 stopped.</para>
926 </listitem>
927 </varlistentry>
928 <varlistentry>
929 <term><filename>veritysetup-pre.target</filename></term>
930 <listitem>
931 <para>This passive target unit may be pulled in by services
932 that want to run before any verity integrity protected block
933 device is set up. All verity integrity protected block
934 devices are set up after this target has been reached. Since
935 the shutdown order is implicitly the reverse start-up order
936 between units, this target is particularly useful to ensure
937 that a service is shut down only after all verity integrity
938 protected block devices are fully stopped.</para>
939 </listitem>
940 </varlistentry>
941 <varlistentry>
942 <term><filename>first-boot-complete.target</filename></term>
943 <listitem>
944 <para>This passive target is intended as a synchronization point for units that need to run once
945 during the first boot. Only after all units ordered before this target have finished, will the
946 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>
947 be committed to disk, marking the first boot as completed. If the boot is aborted at any time
948 before that, the next boot will re-run any units with <varname>ConditionFirstBoot=yes</varname>.
949 </para>
950 </listitem>
951 </varlistentry>
952 <varlistentry>
953 <term><filename>getty-pre.target</filename></term>
954 <listitem>
955 <para>A special passive target unit. Users of this target
956 are expected to pull it in the boot transaction via
957 a dependency (e.g. <varname>Wants=</varname>). Order your
958 unit before this unit if you want to make use of the console
959 just before <filename>getty</filename> is started.
960 </para>
961 </listitem>
962 </varlistentry>
963 <varlistentry>
964 <term><filename>local-fs-pre.target</filename></term>
965 <listitem>
966 <para>This target unit is
967 automatically ordered before
968 all local mount points marked
969 with <option>auto</option>
970 (see above). It can be used to
971 execute certain units before
972 all local mounts.</para>
973 </listitem>
974 </varlistentry>
975 <varlistentry>
976 <term><filename>network.target</filename></term>
977 <listitem>
978 <para>This unit is supposed to indicate when network functionality is available, but it is only
979 very weakly defined what that is supposed to mean. However, the following should apply at
980 minimum:</para>
981
982 <itemizedlist>
983 <listitem><para>At start-up, any configured synthetic network devices (i.e. not physical ones
984 that require hardware to show up and be probed, but virtual ones like bridge devices and
985 similar which are created programmatically) that do not depend on any underlying hardware
986 should be allocated by the time this target is reached. It is not necessary for these
987 interfaces to also have completed IP level configuration by the time
988 <filename>network.target</filename> is reached.</para></listitem>
989
990 <listitem><para>At shutdown, a unit that is ordered after <filename>network.target</filename>
991 will be stopped before the network — to whatever level it might be set up by then — is shut
992 down. It is hence useful when writing service files that require network access on shutdown,
993 which should order themselves after this target, but not pull it in. Also see <ulink
994 url="https://systemd.io/NETWORK_ONLINE">Running Services After
995 the Network is up</ulink> for more information.</para></listitem>
996 </itemizedlist>
997
998 <para>It must emphasized that at start-up there's no guarantee that hardware-based devices have
999 shown up by the time this target is reached, or even acquired complete IP configuration. For that
1000 purpose use <filename>network-online.target</filename> as described above.</para>
1001 </listitem>
1002 </varlistentry>
1003 <varlistentry>
1004 <term><filename>network-pre.target</filename></term>
1005 <listitem>
1006 <para>This passive target unit may be pulled in by services
1007 that want to run before any network is set up, for example
1008 for the purpose of setting up a firewall. All network
1009 management software orders itself after this target, but
1010 does not pull it in.</para>
1011 </listitem>
1012 </varlistentry>
1013 <varlistentry>
1014 <term><filename>nss-lookup.target</filename></term>
1015 <listitem>
1016 <para>A target that should be used as synchronization point for all host/network name
1017 service lookups. Note that this is independent of UNIX user/group name lookups for which
1018 <filename>nss-user-lookup.target</filename> should be used. All services for which the
1019 availability of full host/network name resolution is essential should be ordered after
1020 this target, but not pull it in. systemd automatically adds dependencies of type
1021 <varname>After=</varname> for this target unit to all SysV init script service units
1022 with an LSB header referring to the <literal>$named</literal> facility.</para>
1023 </listitem>
1024 </varlistentry>
1025 <varlistentry>
1026 <term><filename>nss-user-lookup.target</filename></term>
1027 <listitem>
1028 <para>A target that should be used as synchronization point for all regular UNIX
1029 user/group name service lookups. Note that this is independent of host/network name
1030 lookups for which <filename>nss-lookup.target</filename> should be used. All services
1031 for which the availability of the full user/group database is essential should be
1032 ordered after this target, but not pull it in. All services which provide parts of the
1033 user/group database should be ordered before this target, and pull it in. Note that this
1034 unit is only relevant for regular users and groups — system users and groups are
1035 required to be resolvable during earliest boot already, and hence do not need any
1036 special ordering against this target.</para>
1037 </listitem>
1038 </varlistentry>
1039 <varlistentry>
1040 <term><filename>remote-fs-pre.target</filename></term>
1041 <listitem>
1042 <para>This target unit is automatically ordered before all
1043 mount point units (see above) and cryptsetup/veritysetup devices
1044 marked with the <option>_netdev</option>. It can be used to run
1045 certain units before remote encrypted devices and mounts are established.
1046 Note that this unit is generally not part of the initial
1047 transaction, unless the unit that wants to be ordered before
1048 all remote mounts pulls it in via a
1049 <varname>Wants=</varname> type dependency. If the unit wants
1050 to be pulled in by the first remote mount showing up, it
1051 should use <filename>network-online.target</filename> (see
1052 above).</para>
1053 </listitem>
1054 </varlistentry>
1055 <varlistentry>
1056 <term><filename>rpcbind.target</filename></term>
1057 <listitem>
1058 <para>The portmapper/rpcbind pulls in this target and orders
1059 itself before it, to indicate its availability. systemd
1060 automatically adds dependencies of type
1061 <varname>After=</varname> for this target unit to all SysV
1062 init script service units with an LSB header referring to
1063 the <literal>$portmap</literal> facility.</para>
1064 </listitem>
1065 </varlistentry>
1066 <varlistentry>
1067 <term><filename>time-set.target</filename></term>
1068 <listitem>
1069 <para>Services responsible for setting the system clock (<constant>CLOCK_REALTIME</constant>)
1070 from a local source (such as a maintained timestamp file or imprecise real-time clock) should
1071 pull in this target and order themselves before it. Services where approximate, roughly monotonic
1072 time is desired should be ordered after this unit, but not pull it in.</para>
1073
1074 <para>This target does not provide the accuracy guarantees of
1075 <filename>time-sync.target</filename> (see below), however does not depend on remote clock
1076 sources to be reachable, i.e. the target is typically not delayed by network problems and
1077 similar. Use of this target is recommended for services where approximate clock accuracy and
1078 rough monotonicity is desired but activation shall not be delayed for possibly unreliable network
1079 communication.</para>
1080
1081 <para>The service manager automatically adds dependencies of type <varname>After=</varname> for
1082 this target unit to all timer units with at least one <varname>OnCalendar=</varname>
1083 directive.</para>
1084
1085 <para>The
1086 <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
1087 service is a simple daemon that pulls in this target and orders itself before it. Besides
1088 implementing the SNTP network protocol it maintains a timestamp file on disk whose modification
1089 time is regularlary updated. At service start-up the local system clock is set from that modification time,
1090 ensuring it increases roughly monotonically.</para>
1091
1092 <para>Note that ordering a unit after <filename>time-set.target</filename> only has effect if
1093 there's actually a service ordered before it that delays it until the clock is adjusted for rough
1094 monotonicity. Otherwise, this target might get reached before the clock is adjusted to be roughly
1095 monotonic. Enable
1096 <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1097 or an alternative NTP implementation to delay the target.</para>
1098 </listitem>
1099 </varlistentry>
1100 <varlistentry>
1101 <term><filename>time-sync.target</filename></term>
1102 <listitem>
1103 <para>Services indicating completed synchronization of the system clock
1104 (<constant>CLOCK_REALTIME</constant>) to a remote source should pull in this target and order
1105 themselves before it. Services where accurate time is essential should be ordered after this
1106 unit, but not pull it in.</para>
1107
1108 <para>The service manager automatically adds dependencies of type <varname>After=</varname> for
1109 this target unit to all SysV init script service units with an LSB header referring to the
1110 <literal>$time</literal> facility, as well to all timer units with at least one
1111 <varname>OnCalendar=</varname> directive.</para>
1112
1113 <para>This target provides stricter clock accuracy guarantees than
1114 <filename>time-set.target</filename> (see above), but likely requires
1115 network communication and thus introduces unpredictable delays.
1116 Services that require clock accuracy and where network
1117 communication delays are acceptable should use this target. Services that require a less accurate
1118 clock, and only approximate and roughly monotonic clock behaviour should use
1119 <filename>time-set.target</filename> instead.</para>
1120
1121 <para>Note that ordering a unit after <filename>time-sync.target</filename> only has effect if
1122 there's actually a service ordered before it that delays it until clock synchronization is
1123 reached. Otherwise, this target might get reached before the clock is synchronized to any remote
1124 accurate reference clock. When using
1125 <citerefentry><refentrytitle>systemd-timesyncd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1126 enable
1127 <citerefentry><refentrytitle>systemd-time-wait-sync.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
1128 to delay the target; or use an equivalent service for other NTP implementations.</para>
1129
1130 <table>
1131 <title>Comparison</title>
1132 <tgroup cols='2' align='left' colsep='1' rowsep='1'>
1133 <colspec colname="time-set" />
1134 <colspec colname="time-sync" />
1135 <thead>
1136 <row>
1137 <entry><filename>time-set.target</filename></entry>
1138 <entry><filename>time-sync.target</filename></entry>
1139 </row>
1140 </thead>
1141 <tbody>
1142 <row>
1143 <entry>"quick" to reach</entry>
1144 <entry>"slow" to reach</entry>
1145 </row>
1146 <row>
1147 <entry>typically uses local clock sources, boot process not affected by availability of external resources</entry>
1148 <entry>typically uses remote clock sources, inserts dependencies on remote resources into boot process</entry>
1149 </row>
1150 <row>
1151 <entry>reliable, because local</entry>
1152 <entry>unreliable, because typically network involved</entry>
1153 </row>
1154 <row>
1155 <entry>typically guarantees an approximate and roughly monotonic clock only</entry>
1156 <entry>typically guarantees an accurate clock</entry>
1157 </row>
1158 <row>
1159 <entry>implemented by <filename>systemd-timesyncd.service</filename></entry>
1160 <entry>implemented by <filename>systemd-time-wait-sync.service</filename></entry>
1161 </row>
1162 </tbody>
1163 </tgroup>
1164 </table>
1165
1166 </listitem>
1167 </varlistentry>
1168 </variablelist>
1169 </refsect2>
1170
1171 <refsect2>
1172 <title>Special Slice Units</title>
1173
1174 <para>There are four <literal>.slice</literal> units which form the basis of the hierarchy for
1175 assignment of resources for services, users, and virtual machines or containers. See
1176 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>7</manvolnum></citerefentry>
1177 for details about slice units.</para>
1178
1179 <variablelist>
1180 <varlistentry>
1181 <term><filename>-.slice</filename></term>
1182 <listitem>
1183 <para>The root slice is the root of the slice hierarchy. It usually does not contain
1184 units directly, but may be used to set defaults for the whole tree.</para>
1185 </listitem>
1186 </varlistentry>
1187
1188 <varlistentry>
1189 <term><filename>system.slice</filename></term>
1190 <listitem>
1191 <para>By default, all system services started by
1192 <command>systemd</command> are found in this slice.</para>
1193 </listitem>
1194 </varlistentry>
1195
1196 <varlistentry>
1197 <term><filename>user.slice</filename></term>
1198 <listitem>
1199 <para>By default, all user processes and services started on
1200 behalf of the user, including the per-user systemd instance
1201 are found in this slice. This is pulled in by
1202 <filename>systemd-logind.service</filename>.</para>
1203 </listitem>
1204 </varlistentry>
1205
1206 <varlistentry>
1207 <term><filename>machine.slice</filename></term>
1208 <listitem>
1209 <para>By default, all virtual machines and containers
1210 registered with <command>systemd-machined</command> are
1211 found in this slice. This is pulled in by
1212 <filename>systemd-machined.service</filename>.</para>
1213 </listitem>
1214 </varlistentry>
1215 </variablelist>
1216 </refsect2>
1217 </refsect1>
1218
1219 <refsect1>
1220 <title>Units managed by the user service manager</title>
1221
1222 <refsect2>
1223 <title>Special User Units</title>
1224
1225 <para>When systemd runs as a user instance, the following special
1226 units are available:</para>
1227
1228 <variablelist>
1229 <varlistentry>
1230 <term><filename>default.target</filename></term>
1231 <listitem>
1232 <para>This is the main target of the user session, started by default. Various services that
1233 compose the normal user session should be pulled into this target. In this regard,
1234 <filename>default.target</filename> is similar to <filename>multi-user.target</filename> in the
1235 system instance, but it is a real unit, not an alias.</para>
1236 </listitem>
1237 </varlistentry>
1238 </variablelist>
1239
1240 <para>In addition, the following units are available which have definitions similar to their
1241 system counterparts:
1242 <filename>exit.target</filename>,
1243 <filename>shutdown.target</filename>,
1244 <filename>sockets.target</filename>,
1245 <filename>timers.target</filename>,
1246 <filename>paths.target</filename>,
1247 <filename>bluetooth.target</filename>,
1248 <filename>printer.target</filename>,
1249 <filename>smartcard.target</filename>,
1250 <filename>sound.target</filename>.</para>
1251 </refsect2>
1252
1253 <refsect2>
1254 <title>Special Passive User Units</title>
1255
1256 <variablelist>
1257 <varlistentry>
1258 <term><filename>graphical-session.target</filename></term>
1259 <listitem>
1260 <para>This target is active whenever any graphical session is running. It is used to
1261 stop user services which only apply to a graphical (X, Wayland, etc.) session when the
1262 session is terminated. Such services should have
1263 <literal>PartOf=graphical-session.target</literal> in their [Unit]
1264 section. A target for a particular session (e. g.
1265 <filename>gnome-session.target</filename>) starts and stops
1266 <literal>graphical-session.target</literal> with
1267 <literal>BindsTo=graphical-session.target</literal>.</para>
1268
1269 <para>Which services are started by a session target is determined by the
1270 <literal>Wants=</literal> and <literal>Requires=</literal> dependencies. For services
1271 that can be enabled independently, symlinks in <literal>.wants/</literal> and
1272 <literal>.requires/</literal> should be used, see
1273 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
1274 Those symlinks should either be shipped in packages, or should be added dynamically
1275 after installation, for example using <literal>systemctl add-wants</literal>, see
1276 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
1277 </para>
1278
1279 <example>
1280 <title>Nautilus as part of a GNOME session</title>
1281
1282 <para><literal>gnome-session.target</literal> pulls in Nautilus as top-level service:</para>
1283
1284 <programlisting>[Unit]
1285 Description=User systemd services for GNOME graphical session
1286 Wants=nautilus.service
1287 BindsTo=graphical-session.target</programlisting>
1288
1289 <para><literal>nautilus.service</literal> gets stopped when the session stops:</para>
1290
1291 <programlisting>[Unit]
1292 Description=Render the desktop icons with Nautilus
1293 PartOf=graphical-session.target
1294
1295 [Service]
1296</programlisting>
1297 </example>
1298 </listitem>
1299 </varlistentry>
1300
1301 <varlistentry>
1302 <term><filename>graphical-session-pre.target</filename></term>
1303 <listitem>
1304 <para>This target contains services which set up the environment or global configuration
1305 of a graphical session, such as SSH/GPG agents (which need to export an environment
1306 variable into all desktop processes) or migration of obsolete d-conf keys after an OS
1307 upgrade (which needs to happen before starting any process that might use them). This
1308 target must be started before starting a graphical session like
1309 <filename>gnome-session.target</filename>.</para>
1310 </listitem>
1311 </varlistentry>
1312
1313 <varlistentry>
1314 <term><filename>xdg-desktop-autostart.target</filename></term>
1315 <listitem>
1316 <para>The XDG specification defines a way to autostart applications using XDG desktop files.
1317 systemd ships
1318 <citerefentry><refentrytitle>systemd-xdg-autostart-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
1319 for the XDG desktop files in autostart directories. Desktop Environments can opt-in to use this
1320 service by adding a <varname>Wants=</varname> dependency on
1321 <filename>xdg-desktop-autostart.target</filename>.</para>
1322 </listitem>
1323 </varlistentry>
1324 </variablelist>
1325 </refsect2>
1326
1327 <refsect2>
1328 <title>Special User Slice Units</title>
1329
1330 <para>There are four <literal>.slice</literal> units which form the basis of the user hierarchy for
1331 assignment of resources for user applications and services. See
1332 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>7</manvolnum></citerefentry>
1333 for details about slice units and the documentation about
1334 <ulink url="https://systemd.io/DESKTOP_ENVIRONMENTS">Desktop Environments</ulink>
1335 for further information.</para>
1336
1337 <variablelist>
1338 <varlistentry>
1339 <term><filename>-.slice</filename></term>
1340 <listitem>
1341 <para>The root slice is the root of the user's slice hierarchy.
1342 It usually does not contain units directly, but may be used to set defaults for the whole tree.</para>
1343 </listitem>
1344 </varlistentry>
1345
1346 <varlistentry>
1347 <term><filename>app.slice</filename></term>
1348 <listitem>
1349 <para>By default, all user services and applications managed by
1350 <command>systemd</command> are found in this slice.
1351 All interactively launched applications like web browsers and text editors
1352 as well as non-critical services should be placed into this slice.</para>
1353 </listitem>
1354 </varlistentry>
1355
1356 <varlistentry>
1357 <term><filename>session.slice</filename></term>
1358 <listitem>
1359 <para>All essential services and applications required for the
1360 session should use this slice.
1361 These are services that either cannot be restarted easily
1362 or where latency issues may affect the interactivity of the system and applications.
1363 This includes the display server, screen readers and other services such as DBus or XDG portals.
1364 Such services should be configured to be part of this slice by
1365 adding <varname>Slice=session.slice</varname> to their unit files.</para>
1366 </listitem>
1367 </varlistentry>
1368
1369 <varlistentry>
1370 <term><filename>background.slice</filename></term>
1371 <listitem>
1372 <para>All services running low-priority background tasks should use this slice.
1373 This permits resources to be preferentially assigned to the other slices.
1374 Examples include non-interactive tasks like file indexing or backup operations
1375 where latency is not important.</para>
1376 </listitem>
1377 </varlistentry>
1378 </variablelist>
1379 </refsect2>
1380 </refsect1>
1381
1382 <refsect1>
1383 <title>See Also</title>
1384 <para>
1385 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1386 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1387 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1388 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1389 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1390 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1391 <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1392 <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1393 <citerefentry><refentrytitle>user@.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1394 </para>
1395 </refsect1>
1396
1397 </refentry>