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