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