'\" t
.TH "SYSTEMD\&.SPECIAL" "7" "" "systemd 215" "systemd.special"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
systemd.special \- Special systemd units
.SH "SYNOPSIS"
.PP
basic\&.target,
bluetooth\&.target,
ctrl\-alt\-del\&.target,
cryptsetup\&.target,
cryptsetup\-pre\&.target,
dbus\&.service,
dbus\&.socket,
default\&.target,
display\-manager\&.service,
emergency\&.target,
exit\&.target,
final\&.target,
getty\&.target,
graphical\&.target,
halt\&.target,
hibernate\&.target,
hybrid\-sleep\&.target,
initrd\-fs\&.target,
kbrequest\&.target,
kexec\&.target,
local\-fs\&.target,
local\-fs\-pre\&.target,
multi\-user\&.target,
network\&.target,
network\-online\&.target,
network\-pre\&.target,
nss\-lookup\&.target,
nss\-user\-lookup\&.target,
paths\&.target,
poweroff\&.target,
printer\&.target,
reboot\&.target,
remote\-fs\&.target,
remote\-fs\-pre\&.target,
rescue\&.target,
initrd\-root\-fs\&.target,
rpcbind\&.target,
runlevel2\&.target,
runlevel3\&.target,
runlevel4\&.target,
runlevel5\&.target,
shutdown\&.target,
sigpwr\&.target,
sleep\&.target,
smartcard\&.target,
sockets\&.target,
sound\&.target,
suspend\&.target,
swap\&.target,
sysinit\&.target,
syslog\&.socket,
system\-update\&.target,
time\-sync\&.target,
timers\&.target,
umount\&.target,
\-\&.slice,
system\&.slice,
user\&.slice,
machine\&.slice
.SH "DESCRIPTION"
.PP
A few units are treated specially by systemd\&. They have special internal semantics and cannot be renamed\&.
.SH "SPECIAL SYSTEM UNITS"
.PP
basic\&.target
.RS 4
A special target unit covering basic boot\-up\&.
.sp
systemd automatically adds dependencies of the types
\fIRequires=\fR
and
\fIAfter=\fR
for this target unit to all services (except for those with
\fIDefaultDependencies=no\fR)\&.
.sp
Usually this should pull\-in all mount points, swap devices, sockets, timers, and path units and other basic initialization necessary for general purpose daemons\&.
.RE
.PP
ctrl\-alt\-del\&.target
.RS 4
systemd starts this target whenever Control+Alt+Del is pressed on the console\&. Usually this should be aliased (symlinked) to
reboot\&.target\&.
.RE
.PP
cryptsetup\&.target
.RS 4
A target that pulls in setup services for all encrypted block devices\&.
.RE
.PP
dbus\&.service
.RS 4
A special unit for the D\-Bus bus daemon\&. As soon as this service is fully started up systemd will connect to it and register its service\&.
.RE
.PP
dbus\&.socket
.RS 4
A special unit for the D\-Bus system bus socket\&. All units with
\fIType=dbus\fR
automatically gain a dependency on this unit\&.
.RE
.PP
default\&.target
.RS 4
The default unit systemd starts at bootup\&. Usually this should be aliased (symlinked) to
multi\-user\&.target
or
graphical\&.target\&.
.sp
The default unit systemd starts at bootup can be overridden with the
\fIsystemd\&.unit=\fR
kernel command line option\&.
.RE
.PP
display\-manager\&.service
.RS 4
The display manager service\&. Usually this should be aliased (symlinked) to
gdm\&.service
or a similar display manager service\&.
.RE
.PP
emergency\&.target
.RS 4
A special target unit that starts an emergency shell on the main console\&. This unit is supposed to be used with the kernel command line option
\fIsystemd\&.unit=\fR
and has otherwise little use\&.
.RE
.PP
final\&.target
.RS 4
A special target unit that is used during the shutdown logic and may be used to pull in late services after all normal services are already terminated and all mounts unmounted\&.
.RE
.PP
getty\&.target
.RS 4
A special target unit that pulls in statically configured local TTY
getty
instances\&.
.RE
.PP
graphical\&.target
.RS 4
A special target unit for setting up a graphical login screen\&. This pulls in
multi\-user\&.target\&.
.sp
Units that are needed for graphical logins shall add
\fIWants=\fR
dependencies for their unit to this unit (or
multi\-user\&.target) during installation\&. This is best configured via
\fIWantedBy=graphical\&.target\fR
in the unit\*(Aqs
"[Install]"
section\&.
.RE
.PP
hibernate\&.target
.RS 4
A special target unit for hibernating the system\&. This pulls in
sleep\&.target\&.
.RE
.PP
hybrid\-sleep\&.target
.RS 4
A special target unit for hibernating and suspending the system at the same time\&. This pulls in
sleep\&.target\&.
.RE
.PP
halt\&.target
.RS 4
A special target unit for shutting down and halting the system\&. Note that this target is distinct from
poweroff\&.target
in that it generally really just halts the system rather than powering it down\&.
.sp
Applications wanting to halt the system should start this unit\&.
.RE
.PP
initrd\-fs\&.target
.RS 4
\fBsystemd-fstab-generator\fR(3)
automatically adds dependencies of type
\fIBefore=\fR
to
sysroot\-usr\&.mount
and all mount points found in
/etc/fstab
that have
\fBx\-initrd\&.mount\fR
and not have
\fBnoauto\fR
mount options set\&.
.RE
.PP
kbrequest\&.target
.RS 4
systemd starts this target whenever Alt+ArrowUp is pressed on the console\&. This is a good candidate to be aliased (symlinked) to
rescue\&.target\&.
.RE
.PP
kexec\&.target
.RS 4
A special target unit for shutting down and rebooting the system via kexec\&.
.sp
Applications wanting to reboot the system with kexec should start this unit\&.
.RE
.PP
local\-fs\&.target
.RS 4
\fBsystemd-fstab-generator\fR(3)
automatically adds dependencies of type
\fIBefore=\fR
to all mount units that refer to local mount points for this target unit\&. In addition, it adds dependencies of type
\fIWants=\fR
to this target unit for those mounts listed in
/etc/fstab
that have the
\fBauto\fR
mount option set\&.
.sp
systemd automatically adds dependencies of type
\fIAfter=\fR
for this target unit to all SysV init script service units with an LSB header referring to the
"$local_fs"
facility\&.
.RE
.PP
multi\-user\&.target
.RS 4
A special target unit for setting up a multi\-user system (non\-graphical)\&. This is pulled in by
graphical\&.target\&.
.sp
Units that are needed for a multi\-user system shall add
\fIWants=\fR
dependencies for their unit to this unit during installation\&. This is best configured via
\fIWantedBy=multi\-user\&.target\fR
in the unit\*(Aqs
"[Install]"
section\&.
.RE
.PP
network\-online\&.target
.RS 4
Units that strictly require a configured network connection should pull in
network\-online\&.target
(via a
\fIWants=\fR
type dependency) and order themselves after it\&. This target unit is intended to pull in a service that delays further execution until the network is sufficiently set up\&. What precisely this requires is left to the implementation of the network managing service\&.
.sp
Note the distinction between this unit and
network\&.target\&. This unit is an active unit (i\&.e\&. pulled in by the consumer rather than the provider of this functionality) and pulls in a service which possibly adds substantial delays to further execution\&. In contrast,
network\&.target
is a passive unit (i\&.e\&. pulled in by the provider of the functionality, rather than the consumer) that usually does not delay execution much\&. Usually,
network\&.target
is part of the boot of most systems, while
network\-online\&.target
is not, except when at least one unit requires it\&. Also see
\m[blue]\fBRunning Services After the Network is up\fR\m[]\&\s-2\u[1]\d\s+2
for more information\&.
.sp
All mount units for remote network file systems automatically pull in this unit, and order themselves after it\&. Note that networking daemons that simply provide functionality to other hosts generally do not need to pull this in\&.
.RE
.PP
paths\&.target
.RS 4
A special target unit that sets up all path units (see
\fBsystemd.path\fR(5)
for details) that shall be active after boot\&.
.sp
It is recommended that path units installed by applications get pulled in via
\fIWants=\fR
dependencies from this unit\&. This is best configured via a
\fIWantedBy=paths\&.target\fR
in the path unit\*(Aqs
"[Install]"
section\&.
.RE
.PP
poweroff\&.target
.RS 4
A special target unit for shutting down and powering off the system\&.
.sp
Applications wanting to power off the system should start this unit\&.
.sp
runlevel0\&.target
is an alias for this target unit, for compatibility with SysV\&.
.RE
.PP
reboot\&.target
.RS 4
A special target unit for shutting down and rebooting the system\&.
.sp
Applications wanting to reboot the system should start this unit\&.
.sp
runlevel6\&.target
is an alias for this target unit, for compatibility with SysV\&.
.RE
.PP
remote\-fs\&.target
.RS 4
Similar to
local\-fs\&.target, but for remote mount points\&.
.sp
systemd automatically adds dependencies of type
\fIAfter=\fR
for this target unit to all SysV init script service units with an LSB header referring to the
"$remote_fs"
facility\&.
.RE
.PP
rescue\&.target
.RS 4
A special target unit for setting up the base system and a rescue shell\&.
.sp
runlevel1\&.target
is an alias for this target unit, for compatibility with SysV\&.
.RE
.PP
initrd\-root\-fs\&.target
.RS 4
\fBsystemd-fstab-generator\fR(3)
automatically adds dependencies of type
\fIBefore=\fR
to the
sysroot\&.mount
unit, which is generated from the kernel command line\&.
.RE
.PP
runlevel2\&.target, runlevel3\&.target, runlevel4\&.target, runlevel5\&.target
.RS 4
These are targets that are called whenever the SysV compatibility code asks for runlevel 2, 3, 4, 5, respectively\&. It is a good idea to make this an alias for (i\&.e\&. symlink to)
multi\-user\&.target
(for runlevel 2) or
graphical\&.target
(the others)\&.
.RE
.PP
shutdown\&.target
.RS 4
A special target unit that terminates the services on system shutdown\&.
.sp
Services that shall be terminated on system shutdown shall add
\fIConflicts=\fR
dependencies to this unit for their service unit, which is implicitly done when
\fIDefaultDependencies=yes\fR
is set (the default)\&.
.RE
.PP
sigpwr\&.target
.RS 4
A special target that is started when systemd receives the SIGPWR process signal, which is normally sent by the kernel or UPS daemons when power fails\&.
.RE
.PP
sleep\&.target
.RS 4
A special target unit that is pulled in by
suspend\&.target,
hibernate\&.target
and
hybrid\-sleep\&.target
and may be used to hook units into the sleep state logic\&.
.RE
.PP
sockets\&.target
.RS 4
A special target unit that sets up all socket units\&.(see
\fBsystemd.socket\fR(5)
for details) that shall be active after boot\&.
.sp
Services that can be socket\-activated shall add
\fIWants=\fR
dependencies to this unit for their socket unit during installation\&. This is best configured via a
\fIWantedBy=sockets\&.target\fR
in the socket unit\*(Aqs
"[Install]"
section\&.
.RE
.PP
suspend\&.target
.RS 4
A special target unit for suspending the system\&. This pulls in
sleep\&.target\&.
.RE
.PP
swap\&.target
.RS 4
Similar to
local\-fs\&.target, but for swap partitions and swap files\&.
.RE
.PP
sysinit\&.target
.RS 4
A special target unit covering early boot\-up scripts\&.
.RE
.PP
syslog\&.socket
.RS 4
The socket unit syslog implementations should listen on\&. All userspace log messages will be made available on this socket\&. For more information about syslog integration, please consult the
\m[blue]\fBSyslog Interface\fR\m[]\&\s-2\u[2]\d\s+2
document\&.
.RE
.PP
system\-update\&.target
.RS 4
A special target unit that is used for off\-line system updates\&.
\fBsystemd-system-update-generator\fR(8)
will redirect the boot process to this target if
/system\-update
exists\&. For more information see the
\m[blue]\fBSystem Updates Specification\fR\m[]\&\s-2\u[3]\d\s+2\&.
.RE
.PP
timers\&.target
.RS 4
A special target unit that sets up all timer units (see
\fBsystemd.timer\fR(5)
for details) that shall be active after boot\&.
.sp
It is recommended that timer units installed by applications get pulled in via
\fIWants=\fR
dependencies from this unit\&. This is best configured via
\fIWantedBy=timers\&.target\fR
in the timer unit\*(Aqs
"[Install]"
section\&.
.RE
.PP
umount\&.target
.RS 4
A special target unit that umounts all mount and automount points on system shutdown\&.
.sp
Mounts that shall be unmounted on system shutdown shall add Conflicts dependencies to this unit for their mount unit, which is implicitly done when
\fIDefaultDependencies=yes\fR
is set (the default)\&.
.RE
.SH "SPECIAL SYSTEM UNITS FOR DEVICES"
.PP
Some target units are automatically pulled in as devices of certain kinds show up in the system\&. These may be used to automatically activate various services based on the specific type of the available hardware\&.
.PP
bluetooth\&.target
.RS 4
This target is started automatically as soon as a Bluetooth controller is plugged in or becomes available at boot\&.
.sp
This may be used to pull in Bluetooth management daemons dynamically when Bluetooth hardware is found\&.
.RE
.PP
printer\&.target
.RS 4
This target is started automatically as soon as a printer is plugged in or becomes available at boot\&.
.sp
This may be used to pull in printer management daemons dynamically when printer hardware is found\&.
.RE
.PP
smartcard\&.target
.RS 4
This target is started automatically as soon as a smartcard controller is plugged in or becomes available at boot\&.
.sp
This may be used to pull in smartcard management daemons dynamically when smartcard hardware is found\&.
.RE
.PP
sound\&.target
.RS 4
This target is started automatically as soon as a sound card is plugged in or becomes available at boot\&.
.sp
This may be used to pull in audio management daemons dynamically when audio hardware is found\&.
.RE
.SH "SPECIAL PASSIVE SYSTEM UNITS"
.PP
A number of special system targets are defined that can be used to properly order boot\-up of optional services\&. These targets are generally not part of the initial boot transaction, unless they are explicitly pulled in by one of the implementing services\&. Note specifically that these
\fIpassive\fR
target units are generally not pulled in by the consumer of a service, but by the provider of the service\&. This means: a consuming service should order itself after these targets (as appropriate), but not pull it in\&. A providing service should order itself before these targets (as appropriate) and pull it in (via a
\fIWants=\fR
type dependency)\&.
.PP
Note that these passive units cannot be started manually, i\&.e\&.
"systemctl start time\-sync\&.target"
will fail with an error\&. They can only be pulled in by dependency\&. This is enforced since they exist for ordering purposes only and thus are not useful as only unit within a transaction\&.
.PP
cryptsetup\-pre\&.target
.RS 4
This passive target unit may be pulled in by services that want to run before any encrypted block device is set up\&. All encrypted block devices are set up after this target has been reached\&. Since the shutdown order is implicitly the reverse start\-up order between units, this target is particularly useful to ensure that a service is shut down only after all encrypted block devices are fully stopped\&.
.RE
.PP
local\-fs\-pre\&.target
.RS 4
This target unit is automatically ordered before all local mount points marked with
\fBauto\fR
(see above)\&. It can be used to execute certain units before all local mounts\&.
.RE
.PP
network\&.target
.RS 4
This unit is supposed to indicate when network functionality is available, but it is only very weakly defined what that is supposed to mean, with one exception: at shutdown, a unit that is ordered after
network\&.target
will be stopped before the network \-\- to whatever level it might be set up then \-\- is shut down\&. It is hence useful when writing service files that require network access on shutdown, which should order themselves after this target, but not pull it in\&. Also see
\m[blue]\fBRunning Services After the Network is up\fR\m[]\&\s-2\u[1]\d\s+2
for more information\&. Also see
network\-online\&.target
described above\&.
.sp
systemd automatically adds dependencies of type
\fIAfter=\fR
for this target unit to all SysV init script service units with an LSB header referring to the
"$network"
facility\&.
.RE
.PP
network\-pre\&.target
.RS 4
This passive target unit may be pulled in by services that want to run before any network is set up, for example for the purpose of setting up a firewall\&. All network management software orders itself after this target, but does not pull it in\&.
.RE
.PP
nss\-lookup\&.target
.RS 4
A target that should be used as synchronization point for all host/network name service lookups\&. Note that this is independent of user/group name lookups for which
nss\-user\-lookup\&.target
should be used\&. All services for which the availability of full host/network name resolution is essential should be ordered after this target, but not pull it in\&. systemd automatically adds dependencies of type
\fIAfter=\fR
for this target unit to all SysV init script service units with an LSB header referring to the
"$named"
facility\&.
.RE
.PP
nss\-user\-lookup\&.target
.RS 4
A target that should be used as synchronization point for all user/group name service lookups\&. Note that this is independent of host/network name lookups for which
nss\-lookup\&.target
should be used\&. All services for which the availability of the full user/group database is essential should be ordered after this target, but not pull it in\&. Note that system users are always resolvable, and hence do not require any special ordering against this target\&.
.RE
.PP
remote\-fs\-pre\&.target
.RS 4
This target unit is automatically ordered before all remote mount point units (see above)\&. It can be used to run certain units before the remote mounts are established\&. Note that this unit is generally not part of the initial transaction, unless the unit that wants to be ordered before all remote mounts pulls it in via a
\fIWants=\fR
type dependency\&. If the unit wants to be pulled in by the first remote mount showing up, it should use
network\-online\&.target
(see above)\&.
.RE
.PP
rpcbind\&.target
.RS 4
The portmapper/rpcbind pulls in this target and orders itself before it, to indicate its availability\&. systemd automatically adds dependencies of type
\fIAfter=\fR
for this target unit to all SysV init script service units with an LSB header referring to the
"$portmap"
facility\&.
.RE
.PP
time\-sync\&.target
.RS 4
Services responsible for synchronizing the system clock from a remote source (such as NTP client implementations) should pull in this target and order themselves before it\&. All services where correct time is essential should be ordered after this unit, but not pull it in\&. systemd automatically adds dependencies of type
\fIAfter=\fR
for this target unit to all SysV init script service units with an LSB header referring to the
"$time"
facility\&.
.RE
.SH "SPECIAL USER UNITS"
.PP
When systemd runs as a user instance, the following special units are available, which have similar definitions as their system counterparts:
default\&.target,
shutdown\&.target,
sockets\&.target,
timers\&.target,
paths\&.target,
bluetooth\&.target,
printer\&.target,
smartcard\&.target,
sound\&.target\&.
.PP
In addition, the following special unit is understood only when systemd runs as service instance:
.PP
exit\&.target
.RS 4
A special service unit for shutting down the user service manager\&.
.sp
Applications wanting to terminate the user service manager should start this unit\&. If systemd receives
\fBSIGTERM\fR
or
\fBSIGINT\fR
when running as user service daemon, it will start this unit\&.
.sp
Normally, this pulls in
shutdown\&.target
which in turn should be conflicted by all units that want to be shut down on user service manager exit\&.
.RE
.SH "SPECIAL SLICE UNITS"
.PP
There are four
"\&.slice"
units which form the basis of the hierarchy for assignment of resources for services, users, and virtual machines or containers\&.
.PP
\-\&.slice
.RS 4
The root slice is the root of the hierarchy\&. It usually does not contain units directly, but may be used to set defaults for the whole tree\&.
.RE
.PP
system\&.slice
.RS 4
By default, all services services started by
\fBsystemd\fR
are found in this slice\&.
.RE
.PP
user\&.slice
.RS 4
By default, all user processes and services started on behalf of the user, including the per\-user systemd instance are found in this slice\&.
.RE
.PP
machine\&.slice
.RS 4
By default, all virtual machines and containers registered with
\fBsystemd\-machined\fR
are found in this slice\&.
.RE
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1),
\fBsystemd.unit\fR(5),
\fBsystemd.service\fR(5),
\fBsystemd.socket\fR(5),
\fBsystemd.target\fR(5),
\fBsystemd.slice\fR(5),
\fBbootup\fR(7),
\fBsystemd-fstab-generator\fR(8)
.SH "NOTES"
.IP " 1." 4
Running Services After the Network is up
.RS 4
\%http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget
.RE
.IP " 2." 4
Syslog Interface
.RS 4
\%http://www.freedesktop.org/wiki/Software/systemd/syslog
.RE
.IP " 3." 4
System Updates Specification
.RS 4
\%http://freedesktop.org/wiki/Software/systemd/SystemUpdates
.RE