man/systemd.special.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="systemd.special">
  10
  11   <refentryinfo>
  12     <title>systemd.special</title>
  13     <productname>systemd</productname>
  14   </refentryinfo>
  15
  16   <refmeta>
  17     <refentrytitle>systemd.special</refentrytitle>
  18     <manvolnum>7</manvolnum>
  19   </refmeta>
  20
  21   <refnamediv>
  22     <refname>systemd.special</refname>
  23     <refpurpose>Special systemd units</refpurpose>
  24   </refnamediv>
  25
  26   <refsynopsisdiv><para>
  27     <!-- sort alphabetically, targets first --><filename>basic.target</filename>,
  28     <filename>bluetooth.target</filename>,
  29     <filename>cryptsetup-pre.target</filename>,
  30     <filename>cryptsetup.target</filename>,
  31     <filename>ctrl-alt-del.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>final.target</filename>,
  37     <filename>getty.target</filename>,
  38     <filename>getty-pre.target</filename>,
  39     <filename>graphical.target</filename>,
  40     <filename>halt.target</filename>,
  41     <filename>hibernate.target</filename>,
  42     <filename>hybrid-sleep.target</filename>,
  43     <filename>suspend-then-hibernate.target</filename>,
  44     <filename>initrd-fs.target</filename>,
  45     <filename>initrd-root-device.target</filename>,
  46     <filename>initrd-root-fs.target</filename>,
  47     <filename>kbrequest.target</filename>,
  48     <filename>kexec.target</filename>,
  49     <filename>local-fs-pre.target</filename>,
  50     <filename>local-fs.target</filename>,
  51     <filename>machines.target</filename>
  52     <filename>multi-user.target</filename>,
  53     <filename>network-online.target</filename>,
  54     <filename>network-pre.target</filename>,
  55     <filename>network.target</filename>,
  56     <filename>nss-lookup.target</filename>,
  57     <filename>nss-user-lookup.target</filename>,
  58     <filename>paths.target</filename>,
  59     <filename>poweroff.target</filename>,
  60     <filename>printer.target</filename>,
  61     <filename>reboot.target</filename>,
  62     <filename>remote-cryptsetup.target</filename>,
  63     <filename>remote-fs-pre.target</filename>,
  64     <filename>remote-fs.target</filename>,
  65     <filename>rescue.target</filename>,
  66     <filename>rpcbind.target</filename>,
  67     <filename>runlevel2.target</filename>,
  68     <filename>runlevel3.target</filename>,
  69     <filename>runlevel4.target</filename>,
  70     <filename>runlevel5.target</filename>,
  71     <filename>shutdown.target</filename>,
  72     <filename>sigpwr.target</filename>,
  73     <filename>sleep.target</filename>,
  74     <filename>slices.target</filename>,
  75     <filename>smartcard.target</filename>,
  76     <filename>sockets.target</filename>,
  77     <filename>sound.target</filename>,
  78     <filename>suspend.target</filename>,
  79     <filename>swap.target</filename>,
  80     <filename>sysinit.target</filename>,
  81     <filename>system-update.target</filename>,
  82     <filename>system-update-pre.target</filename>,
  83     <filename>time-sync.target</filename>,
  84     <filename>timers.target</filename>,
  85     <filename>umount.target</filename>,
  86     <filename>usb-gadget.target</filename>,
  87     <!-- slices --><filename>-.slice</filename>,
  88     <filename>system.slice</filename>,
  89     <filename>user.slice</filename>,
  90     <filename>machine.slice</filename>,
  91     <!-- the rest --><filename>-.mount</filename>,
  92     <filename>dbus.service</filename>,
  93     <filename>dbus.socket</filename>,
  94     <filename>display-manager.service</filename>,
  95     <filename>init.scope</filename>,
  96     <filename>syslog.socket</filename>,
  97     <filename>system-update-cleanup.service</filename>
  98   </para></refsynopsisdiv>
  99
 100   <refsect1>
 101     <title>Description</title>
 102
 103     <para>A few units are treated specially by systemd. Many of them have
 104     special internal semantics and cannot be renamed, while others simply
 105     have a standard meaning and should be present on all systems.</para>
 106   </refsect1>
 107
 108   <refsect1>
 109     <title>Units managed by the system's service manager</title>
 110
 111     <refsect2>
 112       <title>Special System Units</title>
 113
 114       <variablelist>
 115         <varlistentry>
 116           <term><filename>-.mount</filename></term>
 117           <listitem>
 118             <para>The root mount point, i.e. the mount unit for the <filename>/</filename>
 119             path. This unit is unconditionally active, during the entire time the system is up, as
 120             this mount point is where the basic userspace is running from.</para>
 121           </listitem>
 122         </varlistentry>
 123
 124         <varlistentry>
 125           <term><filename>basic.target</filename></term>
 126           <listitem>
 127             <para>A special target unit covering basic boot-up.</para>
 128
 129             <para>systemd automatically adds dependency of the type
 130             <varname>After=</varname> for this target unit to all
 131             services (except for those with
 132             <varname>DefaultDependencies=no</varname>).</para>
 133
 134             <para>Usually, this should pull-in all local mount points plus
 135             <filename>/var</filename>, <filename>/tmp</filename> and
 136             <filename>/var/tmp</filename>, swap devices, sockets, timers,
 137             path units and other basic initialization necessary for general
 138             purpose daemons. The mentioned mount points are special cased
 139             to allow them to be remote.
 140             </para>
 141
 142             <para>This target usually does not pull in any non-target units
 143             directly, but rather does so indirectly via other early boot targets.
 144             It is instead meant as a synchronization point for late boot
 145             services. Refer to
 146             <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 147             for details on the targets involved.
 148             </para>
 149           </listitem>
 150         </varlistentry>
 151         <varlistentry>
 152           <term><filename>boot-complete.target</filename></term>
 153           <listitem>
 154             <para>This target is intended as generic synchronization point for services that shall determine or act on
 155             whether the boot process completed successfully. Order units that are required to succeed for a boot process
 156             to be considered successful before this unit, and add a <varname>Requires=</varname> dependency from the
 157             target unit to them. Order units that shall only run when the boot process is considered successful after the
 158             target unit and pull in the target from it, also with <varname>Requires=</varname>. Note that by default this
 159             target unit is not part of the initial boot transaction, but is supposed to be pulled in only if required by
 160             units that want to run only on successful boots.</para>
 161
 162             <para>See
 163             <citerefentry><refentrytitle>systemd-boot-check-no-failures.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 164             for a service that implements a generic system health check and orders itself before
 165             <filename>boot-complete.target</filename>.</para>
 166
 167             <para>See
 168             <citerefentry><refentrytitle>systemd-bless-boot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 169             for a service that propagates boot success information to the boot loader, and orders itself after
 170             <filename>boot-complete.target</filename>.</para>
 171           </listitem>
 172         </varlistentry>
 173         <varlistentry>
 174           <term><filename>ctrl-alt-del.target</filename></term>
 175           <listitem>
 176             <para>systemd starts this target whenever Control+Alt+Del is
 177             pressed on the console. Usually, this should be aliased
 178             (symlinked) to <filename>reboot.target</filename>.</para>
 179           </listitem>
 180         </varlistentry>
 181         <varlistentry>
 182           <term><filename>cryptsetup.target</filename></term>
 183           <listitem>
 184             <para>A target that pulls in setup services for all
 185             encrypted block devices.</para>
 186           </listitem>
 187         </varlistentry>
 188         <varlistentry>
 189           <term><filename>dbus.service</filename></term>
 190           <listitem>
 191             <para>A special unit for the D-Bus bus daemon. As soon as
 192             this service is fully started up systemd will connect to it
 193             and register its service.</para>
 194           </listitem>
 195         </varlistentry>
 196         <varlistentry>
 197           <term><filename>dbus.socket</filename></term>
 198           <listitem>
 199             <para>A special unit for the D-Bus system bus socket. All
 200             units with <varname>Type=dbus</varname> automatically gain a
 201             dependency on this unit.</para>
 202           </listitem>
 203         </varlistentry>
 204         <varlistentry>
 205           <term><filename>default.target</filename></term>
 206           <listitem>
 207             <para>The default unit systemd starts at bootup. Usually,
 208             this should be aliased (symlinked) to
 209             <filename>multi-user.target</filename> or
 210             <filename>graphical.target</filename>.</para>
 211
 212             <para>The default unit systemd starts at bootup can be
 213             overridden with the <varname>systemd.unit=</varname> kernel
 214             command line option.</para>
 215           </listitem>
 216         </varlistentry>
 217         <varlistentry>
 218           <term><filename>display-manager.service</filename></term>
 219           <listitem>
 220             <para>The display manager service. Usually, this should be
 221             aliased (symlinked) to <filename>gdm.service</filename> or a
 222             similar display manager service.</para>
 223           </listitem>
 224         </varlistentry>
 225         <varlistentry>
 226           <term><filename>emergency.target</filename></term>
 227           <listitem>
 228             <para>A special target unit that starts an emergency shell on the main console. This
 229             target does not pull in any services or mounts. It is the most minimal version of
 230             starting the system in order to acquire an interactive shell; the only processes running
 231             are usually just the system manager (PID 1) and the shell process. This unit is supposed
 232             to be used with the kernel command line option <varname>systemd.unit=</varname>; it is
 233             also used when a file system check on a required file system fails, and boot-up cannot
 234             continue. Compare with <filename>rescue.target</filename>, which serves a similar
 235             purpose, but also starts the most basic services and mounts all file systems.</para>
 236
 237             <para>Use the <literal>systemd.unit=emergency.target</literal> kernel command line
 238             option to boot into this mode. A short alias for this kernel command line option is
 239             <literal>emergency</literal>, for compatibility with SysV.</para>
 240
 241             <para>In many ways booting into <filename>emergency.target</filename> is similar to the
 242             effect of booting with <literal>init=/bin/sh</literal> on the kernel command line,
 243             except that emergency mode provides you with the full system and service manager, and
 244             allows starting individual units in order to continue the boot process in steps.</para>
 245           </listitem>
 246         </varlistentry>
 247         <varlistentry>
 248           <term><filename>exit.target</filename></term>
 249           <listitem>
 250             <para>A special service unit for shutting down the system or
 251             user service manager. It is equivalent to
 252             <filename>poweroff.target</filename> on non-container
 253             systems, and also works in containers.</para>
 254
 255             <para>systemd will start this unit when it receives the
 256             <constant>SIGTERM</constant> or <constant>SIGINT</constant>
 257             signal when running as user service daemon.</para>
 258
 259             <para>Normally, this (indirectly) pulls in
 260             <filename>shutdown.target</filename>, which in turn should be
 261             conflicted by all units that want to be scheduled for
 262             shutdown when the service manager starts to exit.</para>
 263           </listitem>
 264         </varlistentry>
 265         <varlistentry>
 266           <term><filename>final.target</filename></term>
 267           <listitem>
 268             <para>A special target unit that is used during the shutdown
 269             logic and may be used to pull in late services after all
 270             normal services are already terminated and all mounts
 271             unmounted.
 272             </para>
 273           </listitem>
 274         </varlistentry>
 275         <varlistentry>
 276           <term><filename>getty.target</filename></term>
 277           <listitem>
 278             <para>A special target unit that pulls in statically
 279             configured local TTY <filename>getty</filename> instances.
 280             </para>
 281           </listitem>
 282         </varlistentry>
 283         <varlistentry>
 284           <term><filename>graphical.target</filename></term>
 285           <listitem>
 286             <para>A special target unit for setting up a graphical login
 287             screen. This pulls in
 288             <filename>multi-user.target</filename>.</para>
 289
 290             <para>Units that are needed for graphical logins shall add
 291             <varname>Wants=</varname> dependencies for their unit to
 292             this unit (or <filename>multi-user.target</filename>) during
 293             installation. This is best configured via
 294             <varname>WantedBy=graphical.target</varname> in the unit's
 295             <literal>[Install]</literal> section.</para>
 296           </listitem>
 297         </varlistentry>
 298         <varlistentry>
 299           <term><filename>hibernate.target</filename></term>
 300           <listitem>
 301             <para>A special target unit for hibernating the system. This
 302             pulls in <filename>sleep.target</filename>.</para>
 303           </listitem>
 304         </varlistentry>
 305         <varlistentry>
 306           <term><filename>hybrid-sleep.target</filename></term>
 307           <listitem>
 308             <para>A special target unit for hibernating and suspending
 309             the system at the same time. This pulls in
 310             <filename>sleep.target</filename>.</para>
 311           </listitem>
 312         </varlistentry>
 313         <varlistentry>
 314           <term><filename>suspend-then-hibernate.target</filename></term>
 315           <listitem>
 316             <para>A special target unit for suspending the system for a period
 317             of time, waking it and putting it into hibernate. This pulls in
 318             <filename>sleep.target</filename>.</para>
 319           </listitem>
 320         </varlistentry>
 321
 322         <varlistentry>
 323           <term><filename>halt.target</filename></term>
 324           <listitem>
 325             <para>A special target unit for shutting down and halting
 326             the system. Note that this target is distinct from
 327             <filename>poweroff.target</filename> in that it generally
 328             really just halts the system rather than powering it
 329             down.</para>
 330
 331             <para>Applications wanting to halt the system should not start this unit
 332             directly, but should instead execute <command>systemctl halt</command>
 333             (possibly with the <option>--no-block</option> option) or call
 334             <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 335             <command>org.freedesktop.systemd1.Manager.Halt</command> D-Bus method
 336             directly.</para>
 337           </listitem>
 338         </varlistentry>
 339         <varlistentry>
 340           <term><filename>init.scope</filename></term>
 341           <listitem>
 342             <para>This scope unit is where the system and service manager (PID 1) itself resides. It
 343             is active as long as the system is running.</para>
 344           </listitem>
 345         </varlistentry>
 346         <varlistentry>
 347           <term><filename>initrd-fs.target</filename></term>
 348           <listitem>
 349             <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 350             automatically adds dependencies of type
 351             <varname>Before=</varname> to
 352             <filename>sysroot-usr.mount</filename> and all mount points
 353             found in <filename>/etc/fstab</filename> that have
 354             <option>x-initrd.mount</option> and not have
 355             <option>noauto</option> mount options set.</para>
 356           </listitem>
 357         </varlistentry>
 358         <varlistentry>
 359           <term><filename>initrd-root-device.target</filename></term>
 360           <listitem>
 361             <para>A special initrd target unit that is reached when the root filesystem device is available, but before
 362             it has been mounted.
 363             <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 364             and
 365             <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 366             automatically setup the appropriate dependencies to make this happen.
 367             </para>
 368           </listitem>
 369         </varlistentry>
 370         <varlistentry>
 371           <term><filename>initrd-root-fs.target</filename></term>
 372           <listitem>
 373             <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 374             automatically adds dependencies of type
 375             <varname>Before=</varname> to the
 376             <filename>sysroot.mount</filename> unit, which is generated
 377             from the kernel command line.
 378             </para>
 379           </listitem>
 380         </varlistentry>
 381         <varlistentry>
 382           <term><filename>kbrequest.target</filename></term>
 383           <listitem>
 384             <para>systemd starts this target whenever Alt+ArrowUp is
 385             pressed on the console. Note that any user with physical access
 386             to the machine will be able to do this, without authentication,
 387             so this should be used carefully.</para>
 388           </listitem>
 389         </varlistentry>
 390         <varlistentry>
 391           <term><filename>kexec.target</filename></term>
 392           <listitem>
 393             <para>A special target unit for shutting down and rebooting
 394             the system via kexec.</para>
 395
 396             <para>Applications wanting to reboot the system should not start this unit
 397             directly, but should instead execute <command>systemctl kexec</command>
 398             (possibly with the <option>--no-block</option> option) or call
 399             <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
 400             <command>org.freedesktop.systemd1.Manager.KExec</command> D-Bus method
 401             directly.</para>
 402           </listitem>
 403         </varlistentry>
 404         <varlistentry>
 405           <term><filename>local-fs.target</filename></term>
 406           <listitem>
 407             <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 408             automatically adds dependencies of type
 409             <varname>Before=</varname> to all mount units that refer to
 410             local mount points for this target unit. In addition, it
 411             adds dependencies of type <varname>Wants=</varname> to this
 412             target unit for those mounts listed in
 413             <filename>/etc/fstab</filename> that have the
 414             <option>auto</option> mount option set.</para>
 415           </listitem>
 416         </varlistentry>
 417         <varlistentry>
 418           <term><filename>machines.target</filename></term>
 419           <listitem>
 420             <para>A standard target unit for starting all the containers
 421             and other virtual machines. See <filename>systemd-nspawn@.service</filename>
 422             for an example.</para>
 423           </listitem>
 424         </varlistentry>
 425         <varlistentry>
 426           <term><filename>multi-user.target</filename></term>
 427           <listitem>
 428             <para>A special target unit for setting up a multi-user
 429             system (non-graphical). This is pulled in by
 430             <filename>graphical.target</filename>.</para>
 431
 432             <para>Units that are needed for a multi-user system shall
 433             add <varname>Wants=</varname> dependencies for their unit to
 434             this unit during installation. This is best configured via
 435             <varname>WantedBy=multi-user.target</varname> in the unit's
 436             <literal>[Install]</literal> section.</para>
 437           </listitem>
 438         </varlistentry>
 439         <varlistentry>
 440           <term><filename>network-online.target</filename></term>
 441           <listitem>
 442             <para>Units that strictly require a configured network
 443             connection should pull in
 444             <filename>network-online.target</filename> (via a
 445             <varname>Wants=</varname> type dependency) and order
 446             themselves after it. This target unit is intended to pull in
 447             a service that delays further execution until the network is
 448             sufficiently set up. What precisely this requires is left to
 449             the implementation of the network managing service.</para>
 450
 451             <para>Note the distinction between this unit and
 452             <filename>network.target</filename>. This unit is an active
 453             unit (i.e. pulled in by the consumer rather than the
 454             provider of this functionality) and pulls in a service which
 455             possibly adds substantial delays to further execution. In
 456             contrast, <filename>network.target</filename> is a passive
 457             unit (i.e. pulled in by the provider of the functionality,
 458             rather than the consumer) that usually does not delay
 459             execution much. Usually, <filename>network.target</filename>
 460             is part of the boot of most systems, while
 461             <filename>network-online.target</filename> is not, except
 462             when at least one unit requires it. Also see <ulink
 463             url="https://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running
 464             Services After the Network is up</ulink> for more
 465             information.</para>
 466
 467             <para>All mount units for remote network file systems
 468             automatically pull in this unit, and order themselves after
 469             it. Note that networking daemons that simply provide
 470             functionality to other hosts generally do not need to pull
 471             this in.</para>
 472
 473             <para>systemd automatically adds dependencies of type <varname>Wants=</varname> and
 474             <varname>After=</varname> for this target unit to all SysV init script service units
 475             with an LSB header referring to the <literal>$network</literal> facility.</para>
 476
 477             <para>Note that this unit is only useful during the original system start-up
 478             logic. After the system has completed booting up, it will not track the online state of
 479             the system anymore. Due to this it cannot be used as a network connection monitor
 480             concept, it is purely a one-time system start-up concept.</para>
 481             </listitem>
 482         </varlistentry>
 483         <varlistentry>
 484           <term><filename>paths.target</filename></term>
 485           <listitem>
 486             <para>A special target unit that sets up all path units (see
 487             <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 488             for details) that shall be active after boot.</para>
 489
 490             <para>It is recommended that path units installed by
 491             applications get pulled in via <varname>Wants=</varname>
 492             dependencies from this unit. This is best configured via a
 493             <varname>WantedBy=paths.target</varname> in the path unit's
 494             <literal>[Install]</literal> section.</para>
 495           </listitem>
 496         </varlistentry>
 497         <varlistentry>
 498           <term><filename>poweroff.target</filename></term>
 499           <listitem>
 500             <para>A special target unit for shutting down and powering
 501             off the system.</para>
 502
 503             <para>Applications wanting to power off the system should not start this unit
 504             directly, but should instead execute <command>systemctl poweroff</command>
 505             (possibly with the <option>--no-block</option> option) or call
 506             <citerefentry><refentrytitle>systemd-logind</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
 507             <command>org.freedesktop.login1.Manager.PowerOff</command> D-Bus method
 508             directly.</para>
 509
 510             <para><filename>runlevel0.target</filename> is an alias for
 511             this target unit, for compatibility with SysV.</para>
 512           </listitem>
 513         </varlistentry>
 514         <varlistentry>
 515           <term><filename>reboot.target</filename></term>
 516           <listitem>
 517             <para>A special target unit for shutting down and rebooting
 518             the system.</para>
 519
 520             <para>Applications wanting to reboot the system should not start this unit
 521             directly, but should instead execute <command>systemctl reboot</command>
 522             (possibly with the <option>--no-block</option> option) or call
 523             <citerefentry><refentrytitle>systemd-logind</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
 524             <command>org.freedesktop.login1.Manager.Reboot</command> D-Bus method
 525             directly.</para>
 526
 527             <para><filename>runlevel6.target</filename> is an alias for
 528             this target unit, for compatibility with SysV.</para>
 529           </listitem>
 530         </varlistentry>
 531         <varlistentry>
 532           <term><filename>remote-cryptsetup.target</filename></term>
 533           <listitem>
 534             <para>Similar to <filename>cryptsetup.target</filename>, but for encrypted
 535             devices which are accessed over the network. It is used for
 536             <citerefentry><refentrytitle>crypttab</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 537             entries marked with <option>_netdev</option>.</para>
 538           </listitem>
 539         </varlistentry>
 540         <varlistentry>
 541           <term><filename>remote-fs.target</filename></term>
 542           <listitem>
 543             <para>Similar to <filename>local-fs.target</filename>, but
 544             for remote mount points.</para>
 545
 546             <para>systemd automatically adds dependencies of type
 547             <varname>After=</varname> for this target unit to all SysV
 548             init script service units with an LSB header referring to
 549             the <literal>$remote_fs</literal> facility.</para>
 550           </listitem>
 551         </varlistentry>
 552         <varlistentry>
 553           <term><filename>rescue.target</filename></term>
 554           <listitem>
 555             <para>A special target unit that pulls in the base system (including system mounts) and
 556             spawns a rescue shell. Isolate to this target in order to administer the system in
 557             single-user mode with all file systems mounted but with no services running, except for
 558             the most basic. Compare with <filename>emergency.target</filename>, which is much more
 559             reduced and does not provide the file systems or most basic services. Compare with
 560             <filename>multi-user.target</filename>, this target could be seen as
 561             <filename>single-user.target</filename>.</para>
 562
 563             <para><filename>runlevel1.target</filename> is an alias for this target unit, for
 564             compatibility with SysV.</para>
 565
 566             <para>Use the <literal>systemd.unit=rescue.target</literal> kernel command line option
 567             to boot into this mode. A short alias for this kernel command line option is
 568             <literal>1</literal>, for compatibility with SysV.</para>
 569           </listitem>
 570         </varlistentry>
 571         <varlistentry>
 572           <term><filename>runlevel2.target</filename></term>
 573           <term><filename>runlevel3.target</filename></term>
 574           <term><filename>runlevel4.target</filename></term>
 575           <term><filename>runlevel5.target</filename></term>
 576           <listitem>
 577             <para>These are targets that are called whenever the SysV
 578             compatibility code asks for runlevel 2, 3, 4, 5,
 579             respectively. It is a good idea to make this an alias for
 580             (i.e. symlink to) <filename>graphical.target</filename>
 581             (for runlevel 5) or <filename>multi-user.target</filename>
 582             (the others).</para>
 583           </listitem>
 584         </varlistentry>
 585         <varlistentry>
 586           <term><filename>shutdown.target</filename></term>
 587           <listitem>
 588             <para>A special target unit that terminates the services on
 589             system shutdown.</para>
 590
 591             <para>Services that shall be terminated on system shutdown
 592             shall add <varname>Conflicts=</varname> and
 593             <varname>Before=</varname> dependencies to this unit for
 594             their service unit, which is implicitly done when
 595             <varname>DefaultDependencies=yes</varname> is set (the
 596             default).</para>
 597           </listitem>
 598         </varlistentry>
 599         <varlistentry>
 600           <term><filename>sigpwr.target</filename></term>
 601           <listitem>
 602             <para>A special target that is started when systemd receives
 603             the SIGPWR process signal, which is normally sent by the
 604             kernel or UPS daemons when power fails.</para>
 605           </listitem>
 606         </varlistentry>
 607         <varlistentry>
 608           <term><filename>sleep.target</filename></term>
 609           <listitem>
 610             <para>A special target unit that is pulled in by
 611             <filename>suspend.target</filename>,
 612             <filename>hibernate.target</filename> and
 613             <filename>hybrid-sleep.target</filename> and may be used to
 614             hook units into the sleep state logic.</para>
 615           </listitem>
 616         </varlistentry>
 617         <varlistentry>
 618           <term><filename>slices.target</filename></term>
 619           <listitem>
 620             <para>A special target unit that sets up all slice units (see
 621             <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 622             for details) that shall always be active after boot. By default the generic
 623             <filename>system.slice</filename> slice unit as well as the root slice unit
 624             <filename>-.slice</filename> are pulled in and ordered before this unit (see
 625             below).</para>
 626
 627             <para>Adding slice units to <filename>slices.target</filename> is generally not
 628             necessary. Instead, when some unit that uses <varname>Slice=</varname> is started, the
 629             specified slice will be started automatically. Adding
 630             <varname>WantedBy=slices.target</varname> lines to the <literal>[Install]</literal>
 631             section should only be done for units that need to be always active. In that case care
 632             needs to be taken to avoid creating a loop through the automatic dependencies on
 633             "parent" slices.</para>
 634           </listitem>
 635         </varlistentry>
 636         <varlistentry>
 637           <term><filename>sockets.target</filename></term>
 638           <listitem>
 639             <para>A special target unit that sets up all socket
 640             units (see
 641             <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 642             for details) that shall be active after boot.</para>
 643
 644             <para>Services that can be socket-activated shall add
 645             <varname>Wants=</varname> dependencies to this unit for
 646             their socket unit during installation. This is best
 647             configured via a <varname>WantedBy=sockets.target</varname>
 648             in the socket unit's <literal>[Install]</literal>
 649             section.</para>
 650           </listitem>
 651         </varlistentry>
 652         <varlistentry>
 653           <term><filename>suspend.target</filename></term>
 654           <listitem>
 655             <para>A special target unit for suspending the system. This
 656             pulls in <filename>sleep.target</filename>.</para>
 657           </listitem>
 658         </varlistentry>
 659         <varlistentry>
 660           <term><filename>swap.target</filename></term>
 661           <listitem>
 662             <para>Similar to <filename>local-fs.target</filename>, but
 663             for swap partitions and swap files.</para>
 664           </listitem>
 665         </varlistentry>
 666         <varlistentry>
 667           <term><filename>sysinit.target</filename></term>
 668           <listitem>
 669             <para>systemd automatically adds dependencies of the types
 670             <varname>Requires=</varname> and <varname>After=</varname>
 671             for this target unit to all services (except for those with
 672             <varname>DefaultDependencies=no</varname>).</para>
 673
 674             <para>This target pulls in the services required for system
 675             initialization. System services pulled in by this target should
 676             declare <varname>DefaultDependencies=no</varname> and specify
 677             all their dependencies manually, including access to anything
 678             more than a read only root filesystem. For details on the
 679             dependencies of this target, refer to
 680             <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 681             </para>
 682           </listitem>
 683         </varlistentry>
 684         <varlistentry>
 685           <term><filename>syslog.socket</filename></term>
 686           <listitem>
 687             <para>The socket unit syslog implementations should listen
 688             on. All userspace log messages will be made available on
 689             this socket. For more information about syslog integration,
 690             please consult the <ulink
 691             url="https://www.freedesktop.org/wiki/Software/systemd/syslog">Syslog
 692             Interface</ulink> document.</para>
 693           </listitem>
 694         </varlistentry>
 695         <varlistentry>
 696           <term><filename>system-update.target</filename></term>
 697           <term><filename>system-update-pre.target</filename></term>
 698           <term><filename>system-update-cleanup.service</filename></term>
 699           <listitem>
 700             <para>A special target unit that is used for offline system updates.
 701             <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 702             will redirect the boot process to this target if <filename>/system-update</filename>
 703             exists. For more information see
 704             <citerefentry><refentrytitle>systemd.offline-updates</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 705             </para>
 706
 707             <para>Updates should happen before the <filename>system-update.target</filename> is
 708             reached, and the services which implement them should cause the machine to reboot. The
 709             main units executing the update should order themselves after
 710             <filename>system-update-pre.target</filename> but not pull it in. Services which want to
 711             run during system updates only, but before the actual system update is executed should
 712             order themselves before this unit and pull it in. As a safety measure, if this does not
 713             happen, and <filename>/system-update</filename> still exists after
 714             <filename>system-update.target</filename> is reached,
 715             <filename>system-update-cleanup.service</filename> will remove this symlink and reboot
 716             the machine.</para>
 717           </listitem>
 718         </varlistentry>
 719         <varlistentry>
 720           <term><filename>timers.target</filename></term>
 721           <listitem>
 722             <para>A special target unit that sets up all timer units
 723             (see
 724             <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 725             for details) that shall be active after boot.</para>
 726
 727             <para>It is recommended that timer units installed by
 728             applications get pulled in via <varname>Wants=</varname>
 729             dependencies from this unit. This is best configured via
 730             <varname>WantedBy=timers.target</varname> in the timer
 731             unit's <literal>[Install]</literal> section.</para>
 732           </listitem>
 733         </varlistentry>
 734         <varlistentry>
 735           <term><filename>umount.target</filename></term>
 736           <listitem>
 737             <para>A special target unit that unmounts all mount and
 738             automount points on system shutdown.</para>
 739
 740             <para>Mounts that shall be unmounted on system shutdown
 741             shall add Conflicts dependencies to this unit for their
 742             mount unit, which is implicitly done when
 743             <varname>DefaultDependencies=yes</varname> is set (the
 744             default).</para>
 745           </listitem>
 746         </varlistentry>
 747
 748       </variablelist>
 749     </refsect2>
 750
 751     <refsect2>
 752       <title>Special System Units for Devices</title>
 753
 754       <para>Some target units are automatically pulled in as devices of
 755       certain kinds show up in the system. These may be used to
 756       automatically activate various services based on the specific type
 757       of the available hardware.</para>
 758
 759       <variablelist>
 760         <varlistentry>
 761           <term><filename>bluetooth.target</filename></term>
 762           <listitem>
 763             <para>This target is started automatically as soon as a
 764             Bluetooth controller is plugged in or becomes available at
 765             boot.</para>
 766
 767             <para>This may be used to pull in Bluetooth management
 768             daemons dynamically when Bluetooth hardware is found.</para>
 769           </listitem>
 770         </varlistentry>
 771         <varlistentry>
 772           <term><filename>printer.target</filename></term>
 773           <listitem>
 774             <para>This target is started automatically as soon as a
 775             printer is plugged in or becomes available at boot.</para>
 776
 777             <para>This may be used to pull in printer management daemons
 778             dynamically when printer hardware is found.</para>
 779           </listitem>
 780         </varlistentry>
 781         <varlistentry>
 782           <term><filename>smartcard.target</filename></term>
 783           <listitem>
 784             <para>This target is started automatically as soon as a
 785             smartcard controller is plugged in or becomes available at
 786             boot.</para>
 787
 788             <para>This may be used to pull in smartcard management
 789             daemons dynamically when smartcard hardware is found.</para>
 790           </listitem>
 791         </varlistentry>
 792         <varlistentry>
 793           <term><filename>sound.target</filename></term>
 794           <listitem>
 795             <para>This target is started automatically as soon as a
 796             sound card is plugged in or becomes available at
 797             boot.</para>
 798
 799             <para>This may be used to pull in audio management daemons
 800             dynamically when audio hardware is found.</para>
 801           </listitem>
 802         </varlistentry>
 803         <varlistentry>
 804           <term><filename>usb-gadget.target</filename></term>
 805           <listitem>
 806             <para>This target is started automatically as soon as a
 807             USB Device Controller becomes available at boot.</para>
 808
 809             <para>This may be used to pull in usb gadget
 810             dynamically when UDC hardware is found.</para>
 811           </listitem>
 812         </varlistentry>
 813       </variablelist>
 814     </refsect2>
 815
 816     <refsect2>
 817       <title>Special Passive System Units </title>
 818
 819       <para>A number of special system targets are defined that can be
 820       used to properly order boot-up of optional services. These targets
 821       are generally not part of the initial boot transaction, unless
 822       they are explicitly pulled in by one of the implementing services.
 823       Note specifically that these <emphasis>passive</emphasis> target
 824       units are generally not pulled in by the consumer of a service,
 825       but by the provider of the service. This means: a consuming
 826       service should order itself after these targets (as appropriate),
 827       but not pull it in. A providing service should order itself before
 828       these targets (as appropriate) and pull it in (via a
 829       <varname>Wants=</varname> type dependency).</para>
 830
 831       <para>Note that these passive units cannot be started manually,
 832       i.e. <literal>systemctl start time-sync.target</literal> will fail
 833       with an error. They can only be pulled in by dependency. This is
 834       enforced since they exist for ordering purposes only and thus are
 835       not useful as only unit within a transaction.</para>
 836
 837       <variablelist>
 838         <varlistentry>
 839           <term><filename>cryptsetup-pre.target</filename></term>
 840           <listitem>
 841             <para>This passive target unit may be pulled in by services
 842             that want to run before any encrypted block device is set
 843             up. All encrypted block devices are set up after this target
 844             has been reached. Since the shutdown order is implicitly the
 845             reverse start-up order between units, this target is
 846             particularly useful to ensure that a service is shut down
 847             only after all encrypted block devices are fully
 848             stopped.</para>
 849           </listitem>
 850         </varlistentry>
 851         <varlistentry>
 852           <term><filename>getty-pre.target</filename></term>
 853           <listitem>
 854             <para>A special passive target unit. Users of this target
 855             are expected to pull it in the boot transaction via
 856             a dependency (e.g. <varname>Wants=</varname>). Order your
 857             unit before this unit if you want to make use of the console
 858             just before <filename>getty</filename> is started.
 859             </para>
 860           </listitem>
 861         </varlistentry>
 862         <varlistentry>
 863           <term><filename>local-fs-pre.target</filename></term>
 864           <listitem>
 865             <para>This target unit is
 866             automatically ordered before
 867             all local mount points marked
 868             with <option>auto</option>
 869             (see above). It can be used to
 870             execute certain units before
 871             all local mounts.</para>
 872           </listitem>
 873         </varlistentry>
 874         <varlistentry>
 875           <term><filename>network.target</filename></term>
 876           <listitem>
 877             <para>This unit is supposed to indicate when network
 878             functionality is available, but it is only very weakly
 879             defined what that is supposed to mean, with one exception:
 880             at shutdown, a unit that is ordered after
 881             <filename>network.target</filename> will be stopped before
 882             the network — to whatever level it might be set up then —
 883             is shut down. It is hence useful when writing service files
 884             that require network access on shutdown, which should order
 885             themselves after this target, but not pull it in. Also see
 886             <ulink url="https://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running
 887             Services After the Network is up</ulink> for more
 888             information. Also see
 889             <filename>network-online.target</filename> described
 890             above.</para>
 891           </listitem>
 892         </varlistentry>
 893         <varlistentry>
 894           <term><filename>network-pre.target</filename></term>
 895           <listitem>
 896             <para>This passive target unit may be pulled in by services
 897             that want to run before any network is set up, for example
 898             for the purpose of setting up a firewall. All network
 899             management software orders itself after this target, but
 900             does not pull it in.</para>
 901           </listitem>
 902         </varlistentry>
 903         <varlistentry>
 904           <term><filename>nss-lookup.target</filename></term>
 905           <listitem>
 906             <para>A target that should be used as synchronization point for all host/network name
 907             service lookups. Note that this is independent of UNIX user/group name lookups for which
 908             <filename>nss-user-lookup.target</filename> should be used.  All services for which the
 909             availability of full host/network name resolution is essential should be ordered after
 910             this target, but not pull it in. systemd automatically adds dependencies of type
 911             <varname>After=</varname> for this target unit to all SysV init script service units
 912             with an LSB header referring to the <literal>$named</literal> facility.</para>
 913           </listitem>
 914         </varlistentry>
 915         <varlistentry>
 916           <term><filename>nss-user-lookup.target</filename></term>
 917           <listitem>
 918             <para>A target that should be used as synchronization point for all regular UNIX
 919             user/group name service lookups. Note that this is independent of host/network name
 920             lookups for which <filename>nss-lookup.target</filename> should be used. All services
 921             for which the availability of the full user/group database is essential should be
 922             ordered after this target, but not pull it in. All services which provide parts of the
 923             user/group database should be ordered before this target, and pull it in. Note that this
 924             unit is only relevant for regular users and groups — system users and groups are
 925             required to be resolvable during earliest boot already, and hence do not need any
 926             special ordering against this target.</para>
 927           </listitem>
 928         </varlistentry>
 929         <varlistentry>
 930           <term><filename>remote-fs-pre.target</filename></term>
 931           <listitem>
 932             <para>This target unit is automatically ordered before all
 933             mount point units (see above) and cryptsetup devices
 934             marked with the <option>_netdev</option>. It can be used to run
 935             certain units before remote encrypted devices and mounts are established.
 936             Note that this unit is generally not part of the initial
 937             transaction, unless the unit that wants to be ordered before
 938             all remote mounts pulls it in via a
 939             <varname>Wants=</varname> type dependency. If the unit wants
 940             to be pulled in by the first remote mount showing up, it
 941             should use <filename>network-online.target</filename> (see
 942             above).</para>
 943           </listitem>
 944         </varlistentry>
 945         <varlistentry>
 946           <term><filename>rpcbind.target</filename></term>
 947           <listitem>
 948             <para>The portmapper/rpcbind pulls in this target and orders
 949             itself before it, to indicate its availability. systemd
 950             automatically adds dependencies of type
 951             <varname>After=</varname> for this target unit to all SysV
 952             init script service units with an LSB header referring to
 953             the <literal>$portmap</literal> facility.</para>
 954           </listitem>
 955         </varlistentry>
 956         <varlistentry>
 957           <term><filename>time-sync.target</filename></term>
 958           <listitem>
 959             <para>Services responsible for synchronizing the system
 960             clock from a remote source (such as NTP client
 961             implementations) should pull in this target and order
 962             themselves before it. All services where correct time is
 963             essential should be ordered after this unit, but not pull it
 964             in. systemd automatically adds dependencies of type
 965             <varname>After=</varname> for this target unit to all SysV
 966             init script service units with an LSB header referring to
 967             the <literal>$time</literal> facility. </para>
 968           </listitem>
 969         </varlistentry>
 970       </variablelist>
 971     </refsect2>
 972
 973     <refsect2>
 974       <title>Special Slice Units</title>
 975
 976       <para>There are four <literal>.slice</literal> units which form the basis of the hierarchy for
 977       assignment of resources for services, users, and virtual machines or containers. See
 978       <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 979       for details about slice units.</para>
 980
 981       <variablelist>
 982         <varlistentry>
 983           <term><filename>-.slice</filename></term>
 984           <listitem>
 985             <para>The root slice is the root of the slice hierarchy. It usually does not contain
 986             units directly, but may be used to set defaults for the whole tree.</para>
 987           </listitem>
 988         </varlistentry>
 989
 990         <varlistentry>
 991           <term><filename>system.slice</filename></term>
 992           <listitem>
 993             <para>By default, all system services started by
 994             <command>systemd</command> are found in this slice.</para>
 995           </listitem>
 996         </varlistentry>
 997
 998         <varlistentry>
 999           <term><filename>user.slice</filename></term>
1000           <listitem>
1001             <para>By default, all user processes and services started on
1002             behalf of the user, including the per-user systemd instance
1003             are found in this slice.  This is pulled in by
1004             <filename>systemd-logind.service</filename></para>
1005           </listitem>
1006         </varlistentry>
1007
1008         <varlistentry>
1009           <term><filename>machine.slice</filename></term>
1010           <listitem>
1011             <para>By default, all virtual machines and containers
1012             registered with <command>systemd-machined</command> are
1013             found in this slice.  This is pulled in by
1014             <filename>systemd-machined.service</filename></para>
1015           </listitem>
1016         </varlistentry>
1017       </variablelist>
1018     </refsect2>
1019   </refsect1>
1020
1021   <refsect1>
1022     <title>Units managed by the user's service manager</title>
1023
1024     <refsect2>
1025       <title>Special User Units</title>
1026
1027       <para>When systemd runs as a user instance, the following special
1028       units are available, which have similar definitions as their
1029       system counterparts:
1030       <filename>exit.target</filename>,
1031       <filename>default.target</filename>,
1032       <filename>shutdown.target</filename>,
1033       <filename>sockets.target</filename>,
1034       <filename>timers.target</filename>,
1035       <filename>paths.target</filename>,
1036       <filename>bluetooth.target</filename>,
1037       <filename>printer.target</filename>,
1038       <filename>smartcard.target</filename>,
1039       <filename>sound.target</filename>.</para>
1040     </refsect2>
1041
1042     <refsect2>
1043       <title>Special Passive User Units</title>
1044
1045       <variablelist>
1046         <varlistentry>
1047           <term><filename>graphical-session.target</filename></term>
1048           <listitem>
1049             <para>This target is active whenever any graphical session is running. It is used to
1050             stop user services which only apply to a graphical (X, Wayland, etc.) session when the
1051             session is terminated. Such services should have
1052             <literal>PartOf=graphical-session.target</literal> in their <literal>[Unit]</literal>
1053             section. A target for a particular session (e. g.
1054             <filename>gnome-session.target</filename>) starts and stops
1055             <literal>graphical-session.target</literal> with
1056             <literal>BindsTo=graphical-session.target</literal>.</para>
1057
1058             <para>Which services are started by a session target is determined by the
1059             <literal>Wants=</literal> and <literal>Requires=</literal> dependencies.  For services
1060             that can be enabled independently, symlinks in <literal>.wants/</literal> and
1061             <literal>.requires/</literal> should be used, see
1062             <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
1063             Those symlinks should either be shipped in packages, or should be added dynamically
1064             after installation, for example using <literal>systemctl add-wants</literal>, see
1065             <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
1066             </para>
1067
1068             <example>
1069               <title>Nautilus as part of a GNOME session</title>
1070
1071               <para><literal>gnome-session.target</literal> pulls in Nautilus as top-level service:</para>
1072
1073               <programlisting>[Unit]
1074   Description=User systemd services for GNOME graphical session
1075   Wants=nautilus.service
1076   BindsTo=graphical-session.target</programlisting>
1077
1078               <para><literal>nautilus.service</literal> gets stopped when the session stops:</para>
1079
1080               <programlisting>[Unit]
1081   Description=Render the desktop icons with Nautilus
1082   PartOf=graphical-session.target
1083
1084   [Service]
1085   …</programlisting>
1086             </example>
1087           </listitem>
1088         </varlistentry>
1089
1090         <varlistentry>
1091           <term><filename>graphical-session-pre.target</filename></term>
1092           <listitem>
1093             <para>This target contains services which set up the environment or global configuration
1094             of a graphical session, such as SSH/GPG agents (which need to export an environment
1095             variable into all desktop processes) or migration of obsolete d-conf keys after an OS
1096             upgrade (which needs to happen before starting any process that might use them). This
1097             target must be started before starting a graphical session like
1098             <filename>gnome-session.target</filename>.</para>
1099           </listitem>
1100         </varlistentry>
1101       </variablelist>
1102     </refsect2>
1103   </refsect1>
1104
1105   <refsect1>
1106       <title>See Also</title>
1107       <para>
1108         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1109         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1110         <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1111         <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1112         <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1113         <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1114         <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1115         <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1116         <citerefentry><refentrytitle>user@.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1117       </para>
1118   </refsect1>
1119
1120 </refentry>