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