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