1SYSTEMD.SPECIAL(7)              systemd.special             SYSTEMD.SPECIAL(7)
2
3
4

NAME

6       systemd.special - Special systemd units
7

SYNOPSIS

9       basic.target, bluetooth.target, cryptsetup-pre.target,
10       cryptsetup.target, ctrl-alt-del.target, default.target,
11       emergency.target, exit.target, final.target, getty.target,
12       getty-pre.target, graphical.target, halt.target, hibernate.target,
13       hybrid-sleep.target, suspend-then-hibernate.target, initrd-fs.target,
14       initrd-root-device.target, initrd-root-fs.target, kbrequest.target,
15       kexec.target, local-fs-pre.target, local-fs.target, machines.target
16       multi-user.target, network-online.target, network-pre.target,
17       network.target, nss-lookup.target, nss-user-lookup.target,
18       paths.target, poweroff.target, printer.target, reboot.target,
19       remote-cryptsetup.target, remote-fs-pre.target, remote-fs.target,
20       rescue.target, rpcbind.target, runlevel2.target, runlevel3.target,
21       runlevel4.target, runlevel5.target, shutdown.target, sigpwr.target,
22       sleep.target, slices.target, smartcard.target, sockets.target,
23       sound.target, suspend.target, swap.target, sysinit.target,
24       system-update.target, system-update-pre.target, time-sync.target,
25       timers.target, umount.target, -.slice, system.slice, user.slice,
26       machine.slice, -.mount, dbus.service, dbus.socket,
27       display-manager.service, init.scope, syslog.socket,
28       system-update-cleanup.service
29

DESCRIPTION

31       A few units are treated specially by systemd. Many of them have special
32       internal semantics and cannot be renamed, while others simply have a
33       standard meaning and should be present on all systems.
34

SPECIAL SYSTEM UNITS

36       -.mount
37           The root mount point, i.e. the mount unit for the / path. This unit
38           is unconditionally active, during the entire time the system is up,
39           as this mount point is where the basic userspace is running from.
40
41       basic.target
42           A special target unit covering basic boot-up.
43
44           systemd automatically adds dependency of the type After= for this
45           target unit to all services (except for those with
46           DefaultDependencies=no).
47
48           Usually, this should pull-in all local mount points plus /var, /tmp
49           and /var/tmp, swap devices, sockets, timers, path units and other
50           basic initialization necessary for general purpose daemons. The
51           mentioned mount points are special cased to allow them to be
52           remote.
53
54           This target usually does not pull in any non-target units directly,
55           but rather does so indirectly via other early boot targets. It is
56           instead meant as a synchronization point for late boot services.
57           Refer to bootup(7) for details on the targets involved.
58
59       ctrl-alt-del.target
60           systemd starts this target whenever Control+Alt+Del is pressed on
61           the console. Usually, this should be aliased (symlinked) to
62           reboot.target.
63
64       cryptsetup.target
65           A target that pulls in setup services for all encrypted block
66           devices.
67
68       dbus.service
69           A special unit for the D-Bus bus daemon. As soon as this service is
70           fully started up systemd will connect to it and register its
71           service.
72
73       dbus.socket
74           A special unit for the D-Bus system bus socket. All units with
75           Type=dbus automatically gain a dependency on this unit.
76
77       default.target
78           The default unit systemd starts at bootup. Usually, this should be
79           aliased (symlinked) to multi-user.target or graphical.target.
80
81           The default unit systemd starts at bootup can be overridden with
82           the systemd.unit= kernel command line option.
83
84       display-manager.service
85           The display manager service. Usually, this should be aliased
86           (symlinked) to gdm.service or a similar display manager service.
87
88       emergency.target
89           A special target unit that starts an emergency shell on the main
90           console. This target does not pull in any services or mounts. It is
91           the most minimal version of starting the system in order to acquire
92           an interactive shell; the only processes running are usually just
93           the system manager (PID 1) and the shell process. This unit is
94           supposed to be used with the kernel command line option
95           systemd.unit=; it is also used when a file system check on a
96           required file system fails, and boot-up cannot continue. Compare
97           with rescue.target, which serves a similar purpose, but also starts
98           the most basic services and mounts all file systems.
99
100           Use the "systemd.unit=emergency.target" kernel command line option
101           to boot into this mode. A short alias for this kernel command line
102           option is "emergency", for compatibility with SysV.
103
104           In many ways booting into emergency.target is similar to the effect
105           of booting with "init=/bin/sh" on the kernel command line, except
106           that emergency mode provides you with the full system and service
107           manager, and allows starting individual units in order to continue
108           the boot process in steps.
109
110       exit.target
111           A special service unit for shutting down the system or user service
112           manager. It is equivalent to poweroff.target on non-container
113           systems, and also works in containers.
114
115           systemd will start this unit when it receives the SIGTERM or SIGINT
116           signal when running as user service daemon.
117
118           Normally, this (indirectly) pulls in shutdown.target, which in turn
119           should be conflicted by all units that want to be scheduled for
120           shutdown when the service manager starts to exit.
121
122       final.target
123           A special target unit that is used during the shutdown logic and
124           may be used to pull in late services after all normal services are
125           already terminated and all mounts unmounted.
126
127       getty.target
128           A special target unit that pulls in statically configured local TTY
129           getty instances.
130
131       graphical.target
132           A special target unit for setting up a graphical login screen. This
133           pulls in multi-user.target.
134
135           Units that are needed for graphical logins shall add Wants=
136           dependencies for their unit to this unit (or multi-user.target)
137           during installation. This is best configured via
138           WantedBy=graphical.target in the unit's "[Install]" section.
139
140       hibernate.target
141           A special target unit for hibernating the system. This pulls in
142           sleep.target.
143
144       hybrid-sleep.target
145           A special target unit for hibernating and suspending the system at
146           the same time. This pulls in sleep.target.
147
148       suspend-then-hibernate.target
149           A special target unit for suspending the system for a period of
150           time, waking it and putting it into hibernate. This pulls in
151           sleep.target.
152
153       halt.target
154           A special target unit for shutting down and halting the system.
155           Note that this target is distinct from poweroff.target in that it
156           generally really just halts the system rather than powering it
157           down.
158
159           Applications wanting to halt the system should not start this unit
160           directly, but should instead execute systemctl halt (possibly with
161           the --no-block option) or call systemd(1)'s
162           org.freedesktop.systemd1.Manager.Halt D-Bus method directly.
163
164       init.scope
165           This scope unit is where the system and service manager (PID 1)
166           itself resides. It is active as long as the system is running.
167
168       initrd-fs.target
169           systemd-fstab-generator(3) automatically adds dependencies of type
170           Before= to sysroot-usr.mount and all mount points found in
171           /etc/fstab that have x-initrd.mount and not have noauto mount
172           options set.
173
174       initrd-root-device.target
175           A special initrd target unit that is reached when the root
176           filesystem device is available, but before it has been mounted.
177           systemd-fstab-generator(3) and systemd-gpt-auto-generator(3)
178           automatically setup the appropriate dependencies to make this
179           happen.
180
181       initrd-root-fs.target
182           systemd-fstab-generator(3) automatically adds dependencies of type
183           Before= to the sysroot.mount unit, which is generated from the
184           kernel command line.
185
186       kbrequest.target
187           systemd starts this target whenever Alt+ArrowUp is pressed on the
188           console. Note that any user with physical access to the machine
189           will be able to do this, without authentication, so this should be
190           used carefully.
191
192       kexec.target
193           A special target unit for shutting down and rebooting the system
194           via kexec.
195
196           Applications wanting to reboot the system should not start this
197           unit directly, but should instead execute systemctl kexec (possibly
198           with the --no-block option) or call systemd(1)'s
199           org.freedesktop.systemd1.Manager.KExec D-Bus method directly.
200
201       local-fs.target
202           systemd-fstab-generator(3) automatically adds dependencies of type
203           Before= to all mount units that refer to local mount points for
204           this target unit. In addition, it adds dependencies of type Wants=
205           to this target unit for those mounts listed in /etc/fstab that have
206           the auto mount option set.
207
208       machines.target
209           A standard target unit for starting all the containers and other
210           virtual machines. See systemd-nspawn@.service for an example.
211
212       multi-user.target
213           A special target unit for setting up a multi-user system
214           (non-graphical). This is pulled in by graphical.target.
215
216           Units that are needed for a multi-user system shall add Wants=
217           dependencies for their unit to this unit during installation. This
218           is best configured via WantedBy=multi-user.target in the unit's
219           "[Install]" section.
220
221       network-online.target
222           Units that strictly require a configured network connection should
223           pull in network-online.target (via a Wants= type dependency) and
224           order themselves after it. This target unit is intended to pull in
225           a service that delays further execution until the network is
226           sufficiently set up. What precisely this requires is left to the
227           implementation of the network managing service.
228
229           Note the distinction between this unit and network.target. This
230           unit is an active unit (i.e. pulled in by the consumer rather than
231           the provider of this functionality) and pulls in a service which
232           possibly adds substantial delays to further execution. In contrast,
233           network.target is a passive unit (i.e. pulled in by the provider of
234           the functionality, rather than the consumer) that usually does not
235           delay execution much. Usually, network.target is part of the boot
236           of most systems, while network-online.target is not, except when at
237           least one unit requires it. Also see Running Services After the
238           Network is up[1] for more information.
239
240           All mount units for remote network file systems automatically pull
241           in this unit, and order themselves after it. Note that networking
242           daemons that simply provide functionality to other hosts generally
243           do not need to pull this in.
244
245           systemd automatically adds dependencies of type Wants= and After=
246           for this target unit to all SysV init script service units with an
247           LSB header referring to the "$network" facility.
248
249           Note that this unit is only useful during the original system
250           start-up logic. After the system has completed booting up, it will
251           not track the online state of the system anymore. Due to this it
252           cannot be used as a network connection monitor concept, it is
253           purely a one-time system start-up concept.
254
255       paths.target
256           A special target unit that sets up all path units (see
257           systemd.path(5) for details) that shall be active after boot.
258
259           It is recommended that path units installed by applications get
260           pulled in via Wants= dependencies from this unit. This is best
261           configured via a WantedBy=paths.target in the path unit's
262           "[Install]" section.
263
264       poweroff.target
265           A special target unit for shutting down and powering off the
266           system.
267
268           Applications wanting to power off the system should not start this
269           unit directly, but should instead execute systemctl poweroff
270           (possibly with the --no-block option) or call systemd-logind(8)'s
271           org.freedesktop.login1.Manager.PowerOff D-Bus method directly.
272
273           runlevel0.target is an alias for this target unit, for
274           compatibility with SysV.
275
276       reboot.target
277           A special target unit for shutting down and rebooting the system.
278
279           Applications wanting to reboot the system should not start this
280           unit directly, but should instead execute systemctl reboot
281           (possibly with the --no-block option) or call systemd-logind(8)'s
282           org.freedesktop.login1.Manager.Reboot D-Bus method directly.
283
284           runlevel6.target is an alias for this target unit, for
285           compatibility with SysV.
286
287       remote-cryptsetup.target
288           Similar to cryptsetup.target, but for encrypted devices which are
289           accessed over the network. It is used for crypttab(8) entries
290           marked with _netdev.
291
292       remote-fs.target
293           Similar to local-fs.target, but for remote mount points.
294
295           systemd automatically adds dependencies of type After= for this
296           target unit to all SysV init script service units with an LSB
297           header referring to the "$remote_fs" facility.
298
299       rescue.target
300           A special target unit that pulls in the base system (including
301           system mounts) and spawns a rescue shell. Isolate to this target in
302           order to administer the system in single-user mode with all file
303           systems mounted but with no services running, except for the most
304           basic. Compare with emergency.target, which is much more reduced
305           and does not provide the file systems or most basic services.
306           Compare with multi-user.target, this target could be seen as
307           single-user.target.
308
309           runlevel1.target is an alias for this target unit, for
310           compatibility with SysV.
311
312           Use the "systemd.unit=rescue.target" kernel command line option to
313           boot into this mode. A short alias for this kernel command line
314           option is "1", for compatibility with SysV.
315
316       runlevel2.target, runlevel3.target, runlevel4.target, runlevel5.target
317           These are targets that are called whenever the SysV compatibility
318           code asks for runlevel 2, 3, 4, 5, respectively. It is a good idea
319           to make this an alias for (i.e. symlink to) graphical.target (for
320           runlevel 5) or multi-user.target (the others).
321
322       shutdown.target
323           A special target unit that terminates the services on system
324           shutdown.
325
326           Services that shall be terminated on system shutdown shall add
327           Conflicts= and Before= dependencies to this unit for their service
328           unit, which is implicitly done when DefaultDependencies=yes is set
329           (the default).
330
331       sigpwr.target
332           A special target that is started when systemd receives the SIGPWR
333           process signal, which is normally sent by the kernel or UPS daemons
334           when power fails.
335
336       sleep.target
337           A special target unit that is pulled in by suspend.target,
338           hibernate.target and hybrid-sleep.target and may be used to hook
339           units into the sleep state logic.
340
341       slices.target
342           A special target unit that sets up all slice units (see
343           systemd.slice(5) for details) that shall be active after boot. By
344           default the generic system.slice slice unit, as well as the root
345           slice unit -.slice, is pulled in and ordered before this unit (see
346           below).
347
348           It's a good idea to add WantedBy=slices.target lines to the
349           "[Install]" section of all slices units that may be installed
350           dynamically.
351
352       sockets.target
353           A special target unit that sets up all socket units (see
354           systemd.socket(5) for details) that shall be active after boot.
355
356           Services that can be socket-activated shall add Wants= dependencies
357           to this unit for their socket unit during installation. This is
358           best configured via a WantedBy=sockets.target in the socket unit's
359           "[Install]" section.
360
361       suspend.target
362           A special target unit for suspending the system. This pulls in
363           sleep.target.
364
365       swap.target
366           Similar to local-fs.target, but for swap partitions and swap files.
367
368       sysinit.target
369           systemd automatically adds dependencies of the types Requires= and
370           After= for this target unit to all services (except for those with
371           DefaultDependencies=no).
372
373           This target pulls in the services required for system
374           initialization. System services pulled in by this target should
375           declare DefaultDependencies=no and specify all their dependencies
376           manually, including access to anything more than a read only root
377           filesystem. For details on the dependencies of this target, refer
378           to bootup(7).
379
380       syslog.socket
381           The socket unit syslog implementations should listen on. All
382           userspace log messages will be made available on this socket. For
383           more information about syslog integration, please consult the
384           Syslog Interface[2] document.
385
386       system-update.target, system-update-pre.target,
387       system-update-cleanup.service
388           A special target unit that is used for offline system updates.
389           systemd-system-update-generator(8) will redirect the boot process
390           to this target if /system-update exists. For more information see
391           systemd.offline-updates(7).
392
393           Updates should happen before the system-update.target is reached,
394           and the services which implement them should cause the machine to
395           reboot. The main units executing the update should order themselves
396           after system-update-pre.target but not pull it in. Services which
397           want to run during system updates only, but before the actual
398           system update is executed should order themselves before this unit
399           and pull it in. As a safety measure, if this does not happen, and
400           /system-update still exists after system-update.target is reached,
401           system-update-cleanup.service will remove this symlink and reboot
402           the machine.
403
404       timers.target
405           A special target unit that sets up all timer units (see
406           systemd.timer(5) for details) that shall be active after boot.
407
408           It is recommended that timer units installed by applications get
409           pulled in via Wants= dependencies from this unit. This is best
410           configured via WantedBy=timers.target in the timer unit's
411           "[Install]" section.
412
413       umount.target
414           A special target unit that unmounts all mount and automount points
415           on system shutdown.
416
417           Mounts that shall be unmounted on system shutdown shall add
418           Conflicts dependencies to this unit for their mount unit, which is
419           implicitly done when DefaultDependencies=yes is set (the default).
420

SPECIAL SYSTEM UNITS FOR DEVICES

422       Some target units are automatically pulled in as devices of certain
423       kinds show up in the system. These may be used to automatically
424       activate various services based on the specific type of the available
425       hardware.
426
427       bluetooth.target
428           This target is started automatically as soon as a Bluetooth
429           controller is plugged in or becomes available at boot.
430
431           This may be used to pull in Bluetooth management daemons
432           dynamically when Bluetooth hardware is found.
433
434       printer.target
435           This target is started automatically as soon as a printer is
436           plugged in or becomes available at boot.
437
438           This may be used to pull in printer management daemons dynamically
439           when printer hardware is found.
440
441       smartcard.target
442           This target is started automatically as soon as a smartcard
443           controller is plugged in or becomes available at boot.
444
445           This may be used to pull in smartcard management daemons
446           dynamically when smartcard hardware is found.
447
448       sound.target
449           This target is started automatically as soon as a sound card is
450           plugged in or becomes available at boot.
451
452           This may be used to pull in audio management daemons dynamically
453           when audio hardware is found.
454

SPECIAL PASSIVE SYSTEM UNITS

456       A number of special system targets are defined that can be used to
457       properly order boot-up of optional services. These targets are
458       generally not part of the initial boot transaction, unless they are
459       explicitly pulled in by one of the implementing services. Note
460       specifically that these passive target units are generally not pulled
461       in by the consumer of a service, but by the provider of the service.
462       This means: a consuming service should order itself after these targets
463       (as appropriate), but not pull it in. A providing service should order
464       itself before these targets (as appropriate) and pull it in (via a
465       Wants= type dependency).
466
467       Note that these passive units cannot be started manually, i.e.
468       "systemctl start time-sync.target" will fail with an error. They can
469       only be pulled in by dependency. This is enforced since they exist for
470       ordering purposes only and thus are not useful as only unit within a
471       transaction.
472
473       cryptsetup-pre.target
474           This passive target unit may be pulled in by services that want to
475           run before any encrypted block device is set up. All encrypted
476           block devices are set up after this target has been reached. Since
477           the shutdown order is implicitly the reverse start-up order between
478           units, this target is particularly useful to ensure that a service
479           is shut down only after all encrypted block devices are fully
480           stopped.
481
482       getty-pre.target
483           A special passive target unit. Users of this target are expected to
484           pull it in the boot transaction via a dependency (e.g.  Wants=).
485           Order your unit before this unit if you want to make use of the
486           console just before getty is started.
487
488       local-fs-pre.target
489           This target unit is automatically ordered before all local mount
490           points marked with auto (see above). It can be used to execute
491           certain units before all local mounts.
492
493       network.target
494           This unit is supposed to indicate when network functionality is
495           available, but it is only very weakly defined what that is supposed
496           to mean, with one exception: at shutdown, a unit that is ordered
497           after network.target will be stopped before the network — to
498           whatever level it might be set up then — is shut down. It is hence
499           useful when writing service files that require network access on
500           shutdown, which should order themselves after this target, but not
501           pull it in. Also see Running Services After the Network is up[1]
502           for more information. Also see network-online.target described
503           above.
504
505       network-pre.target
506           This passive target unit may be pulled in by services that want to
507           run before any network is set up, for example for the purpose of
508           setting up a firewall. All network management software orders
509           itself after this target, but does not pull it in.
510
511       nss-lookup.target
512           A target that should be used as synchronization point for all
513           host/network name service lookups. Note that this is independent of
514           UNIX user/group name lookups for which nss-user-lookup.target
515           should be used. All services for which the availability of full
516           host/network name resolution is essential should be ordered after
517           this target, but not pull it in. systemd automatically adds
518           dependencies of type After= for this target unit to all SysV init
519           script service units with an LSB header referring to the "$named"
520           facility.
521
522       nss-user-lookup.target
523           A target that should be used as synchronization point for all
524           regular UNIX user/group name service lookups. Note that this is
525           independent of host/network name lookups for which
526           nss-lookup.target should be used. All services for which the
527           availability of the full user/group database is essential should be
528           ordered after this target, but not pull it in. All services which
529           provide parts of the user/group database should be ordered before
530           this target, and pull it in. Note that this unit is only relevant
531           for regular users and groups — system users and groups are required
532           to be resolvable during earliest boot already, and hence do not
533           need any special ordering against this target.
534
535       remote-fs-pre.target
536           This target unit is automatically ordered before all mount point
537           units (see above) and cryptsetup devices marked with the _netdev.
538           It can be used to run certain units before remote encrypted devices
539           and mounts are established. Note that this unit is generally not
540           part of the initial transaction, unless the unit that wants to be
541           ordered before all remote mounts pulls it in via a Wants= type
542           dependency. If the unit wants to be pulled in by the first remote
543           mount showing up, it should use network-online.target (see above).
544
545       rpcbind.target
546           The portmapper/rpcbind pulls in this target and orders itself
547           before it, to indicate its availability. systemd automatically adds
548           dependencies of type After= for this target unit to all SysV init
549           script service units with an LSB header referring to the "$portmap"
550           facility.
551
552       time-sync.target
553           Services responsible for synchronizing the system clock from a
554           remote source (such as NTP client implementations) should pull in
555           this target and order themselves before it. All services where
556           correct time is essential should be ordered after this unit, but
557           not pull it in. systemd automatically adds dependencies of type
558           After= for this target unit to all SysV init script service units
559           with an LSB header referring to the "$time" facility.
560

SPECIAL USER UNITS

562       When systemd runs as a user instance, the following special units are
563       available, which have similar definitions as their system counterparts:
564       exit.target, default.target, shutdown.target, sockets.target,
565       timers.target, paths.target, bluetooth.target, printer.target,
566       smartcard.target, sound.target.
567

SPECIAL PASSIVE USER UNITS

569       graphical-session.target
570           This target is active whenever any graphical session is running. It
571           is used to stop user services which only apply to a graphical (X,
572           Wayland, etc.) session when the session is terminated. Such
573           services should have "PartOf=graphical-session.target" in their
574           "[Unit]" section. A target for a particular session (e. g.
575           gnome-session.target) starts and stops "graphical-session.target"
576           with "BindsTo=graphical-session.target".
577
578           Which services are started by a session target is determined by the
579           "Wants=" and "Requires=" dependencies. For services that can be
580           enabled independently, symlinks in ".wants/" and ".requires/"
581           should be used, see systemd.unit(5). Those symlinks should either
582           be shipped in packages, or should be added dynamically after
583           installation, for example using "systemctl add-wants", see
584           systemctl(1).
585
586           Example 1. Nautilus as part of a GNOME session
587           "gnome-session.target" pulls in Nautilus as top-level service:
588
589               [Unit]
590               Description=User systemd services for GNOME graphical session
591               Wants=nautilus.service
592               BindsTo=graphical-session.target
593
594           "nautilus.service" gets stopped when the session stops:
595
596               [Unit]
597               Description=Render the desktop icons with Nautilus
598               PartOf=graphical-session.target
599
600               [Service]
601               ...
602
603       graphical-session-pre.target
604           This target contains services which set up the environment or
605           global configuration of a graphical session, such as SSH/GPG agents
606           (which need to export an environment variable into all desktop
607           processes) or migration of obsolete d-conf keys after an OS upgrade
608           (which needs to happen before starting any process that might use
609           them). This target must be started before starting a graphical
610           session like gnome-session.target.
611

SPECIAL SLICE UNITS

613       There are four ".slice" units which form the basis of the hierarchy for
614       assignment of resources for services, users, and virtual machines or
615       containers. See systemd.slice(7) for details about slice units.
616
617       -.slice
618           The root slice is the root of the slice hierarchy. It usually does
619           not contain units directly, but may be used to set defaults for the
620           whole tree.
621
622       system.slice
623           By default, all system services started by systemd are found in
624           this slice.
625
626       user.slice
627           By default, all user processes and services started on behalf of
628           the user, including the per-user systemd instance are found in this
629           slice. This is pulled in by systemd-logind.service
630
631       machine.slice
632           By default, all virtual machines and containers registered with
633           systemd-machined are found in this slice. This is pulled in by
634           systemd-machined.service
635

SEE ALSO

637       systemd(1), systemd.unit(5), systemd.service(5), systemd.socket(5),
638       systemd.target(5), systemd.slice(5), bootup(7), systemd-fstab-
639       generator(8)
640

NOTES

642        1. Running Services After the Network is up
643           https://www.freedesktop.org/wiki/Software/systemd/NetworkTarget
644
645        2. Syslog Interface
646           https://www.freedesktop.org/wiki/Software/systemd/syslog
647
648
649
650systemd 239                                                 SYSTEMD.SPECIAL(7)
Impressum