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