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