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