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