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">
6 This file is part of systemd.
8 Copyright 2010 Lennart Poettering
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.
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.
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/>.
24 <refentry id="systemd.special">
27 <title>systemd.special</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
41 <refentrytitle>systemd.special</refentrytitle>
42 <manvolnum>7</manvolnum>
46 <refname>systemd.special</refname>
47 <refpurpose>Special systemd units</refpurpose>
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>dbus.service</filename>,
56 <filename>dbus.socket</filename>,
57 <filename>default.target</filename>,
58 <filename>display-manager.service</filename>,
59 <filename>emergency.target</filename>,
60 <filename>exit.target</filename>,
61 <filename>final.target</filename>,
62 <filename>getty.target</filename>,
63 <filename>graphical.target</filename>,
64 <filename>halt.target</filename>,
65 <filename>hibernate.target</filename>,
66 <filename>hybrid-sleep.target</filename>,
67 <filename>initrd-fs.target</filename>,
68 <filename>kbrequest.target</filename>,
69 <filename>kexec.target</filename>,
70 <filename>local-fs.target</filename>,
71 <filename>local-fs-pre.target</filename>,
72 <filename>multi-user.target</filename>,
73 <filename>network.target</filename>,
74 <filename>network-online.target</filename>,
75 <filename>nss-lookup.target</filename>,
76 <filename>nss-user-lookup.target</filename>,
77 <filename>paths.target</filename>,
78 <filename>poweroff.target</filename>,
79 <filename>printer.target</filename>,
80 <filename>reboot.target</filename>,
81 <filename>remote-fs.target</filename>,
82 <filename>remote-fs-pre.target</filename>,
83 <filename>rescue.target</filename>,
84 <filename>initrd-root-fs.target</filename>,
85 <filename>rpcbind.target</filename>,
86 <filename>runlevel2.target</filename>,
87 <filename>runlevel3.target</filename>,
88 <filename>runlevel4.target</filename>,
89 <filename>runlevel5.target</filename>,
90 <filename>shutdown.target</filename>,
91 <filename>sigpwr.target</filename>,
92 <filename>sleep.target</filename>,
93 <filename>smartcard.target</filename>,
94 <filename>sockets.target</filename>,
95 <filename>sound.target</filename>,
96 <filename>suspend.target</filename>,
97 <filename>swap.target</filename>,
98 <filename>sysinit.target</filename>,
99 <filename>syslog.socket</filename>,
100 <filename>system-update.target</filename>,
101 <filename>time-sync.target</filename>,
102 <filename>timers.target</filename>,
103 <filename>umount.target</filename>,
104 <filename>-.slice</filename>,
105 <filename>system.slice</filename>,
106 <filename>user.slice</filename>,
107 <filename>machine.slice</filename></para>
111 <title>Description</title>
113 <para>A few units are treated specially by
114 systemd. They have special internal semantics and
115 cannot be renamed.</para>
119 <title>Special System Units</title>
123 <term><filename>basic.target</filename></term>
125 <para>A special target unit
126 covering basic boot-up.</para>
127 <para>systemd automatically
128 adds dependencies of the types
129 <varname>Requires=</varname>
130 and <varname>After=</varname>
131 for this target unit to all
132 services (except for those
134 <varname>DefaultDependencies=no</varname>).</para>
136 <para>Usually this should
137 pull-in all mount points, swap
138 devices, sockets, timers, and
139 path units and other basic
140 initialization necessary for
146 <term><filename>ctrl-alt-del.target</filename></term>
148 <para>systemd starts this
150 Control+Alt+Del is pressed on
151 the console. Usually this
152 should be aliased (symlinked)
154 <filename>reboot.target</filename>.</para>
158 <term><filename>cryptsetup.target</filename></term>
160 <para>A target that pulls in
161 setup services for all
167 <term><filename>dbus.service</filename></term>
169 <para>A special unit for the
170 D-Bus bus daemon. As soon as
171 this service is fully started
172 up systemd will connect to it
178 <term><filename>dbus.socket</filename></term>
180 <para>A special unit for the
181 D-Bus system bus socket. All
183 <varname>Type=dbus</varname>
190 <term><filename>default.target</filename></term>
192 <para>The default unit systemd
193 starts at bootup. Usually this
194 should be aliased (symlinked)
196 <filename>multi-user.target</filename>
198 <filename>graphical.target</filename>.</para>
200 <para>The default unit systemd
201 starts at bootup can be
203 <varname>systemd.unit=</varname>
204 kernel command line option.</para>
208 <term><filename>display-manager.service</filename></term>
210 <para>The display manager
211 service. Usually this should
212 be aliased (symlinked) to
213 <filename>gdm.service</filename>
214 or a similar display manager
219 <term><filename>emergency.target</filename></term>
221 <para>A special target unit
222 that starts an emergency
224 console. This unit is supposed
225 to be used with the kernel
227 <varname>systemd.unit=</varname>
228 and has otherwise little use.
233 <term><filename>final.target</filename></term>
235 <para>A special target unit
236 that is used during the
237 shutdown logic and may be used
238 to pull in late services after
239 all normal services are
240 already terminated and all
246 <term><filename>getty.target</filename></term>
248 <para>A special target unit
249 that pulls in statically
251 <filename>getty</filename>
257 <term><filename>graphical.target</filename></term>
259 <para>A special target unit
260 for setting up a graphical
261 login screen. This pulls in
262 <filename>multi-user.target</filename>.</para>
264 <para>Units that are needed
265 for graphical logins shall add
266 <varname>Wants=</varname>
267 dependencies for their unit to
269 <filename>multi-user.target</filename>)
270 during installation. This is
272 <varname>WantedBy=graphical.target</varname>
274 <literal>[Install]</literal>
279 <term><filename>hibernate.target</filename></term>
281 <para>A special target unit
283 system. This pulls in
284 <filename>sleep.target</filename>.</para>
288 <term><filename>hybrid-sleep.target</filename></term>
290 <para>A special target unit
291 for hibernating and suspending the
292 system at the same time. This pulls in
293 <filename>sleep.target</filename>.</para>
297 <term><filename>halt.target</filename></term>
299 <para>A special target unit
300 for shutting down and halting
301 the system. Note that this
302 target is distinct from
303 <filename>poweroff.target</filename>
304 in that it generally really
305 just halts the system rather
306 than powering it down.</para>
308 <para>Applications wanting to
309 halt the system should start
314 <term><filename>initrd-fs.target</filename></term>
316 <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry>
319 <varname>Before=</varname> to
320 <filename>sysroot-usr.mount</filename>
321 and all mount points found in
322 <filename>/etc/fstab</filename>
324 <option>auto</option> and
325 <option>x-initrd.mount</option>
331 <term><filename>kbrequest.target</filename></term>
333 <para>systemd starts this
334 target whenever Alt+ArrowUp is
335 pressed on the console. This
336 is a good candidate to be
337 aliased (symlinked) to
338 <filename>rescue.target</filename>.</para>
342 <term><filename>kexec.target</filename></term>
344 <para>A special target unit
345 for shutting down and rebooting the system via kexec.</para>
347 <para>Applications wanting to
348 reboot the system with kexec should start
353 <term><filename>local-fs.target</filename></term>
355 <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry>
358 <varname>Before=</varname> to
359 all mount units that refer to
360 local mount points for this
361 target unit. In addition, it
362 adds dependencies of type
363 <varname>Wants=</varname> to
364 this target unit for those
366 <filename>/etc/fstab</filename>
368 <option>auto</option> mount
373 <term><filename>multi-user.target</filename></term>
375 <para>A special target unit
376 for setting up a multi-user
377 system (non-graphical). This
379 <filename>graphical.target</filename>.</para>
381 <para>Units that are needed
382 for a multi-user system shall
383 add <varname>Wants=</varname>
384 dependencies for their unit to
386 installation. This is best
388 <varname>WantedBy=multi-user.target</varname>
390 <literal>[Install]</literal>
395 <term><filename>network-online.target</filename></term>
397 <para>Units that strictly
398 require a configured network
399 connection should pull in
400 <filename>network-online.target</filename>
402 <varname>Wants=</varname> type
403 dependency) and order
404 themselves after it. This
405 target unit is intended to
406 pull in a service that delays
407 further execution until the
408 network is sufficiently set
409 up. What precisely this
410 requires is left to the
411 implementation of the network
412 managing service.</para>
414 <para>Note the distinction
415 between this unit and
416 <filename>network.target</filename>. This
417 unit is an active unit
418 (i.e. pulled in by the
419 consumer rather than the
421 functionality) and pulls in a
422 service which possibly adds
423 substantial delays to further
424 execution. In contrast,
425 <filename>network.target</filename>
426 is a passive unit (i.e. pulled
427 in by the provider of the
428 functionality, rather than the
429 consumer) that usually does
432 <filename>network.target</filename>
433 is part of the boot of most
435 <filename>network-online.target</filename>
436 is not, except when at least
437 one unit requires it. Also see
439 url="http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running
440 Services After the Network is
444 <para>All mount units for
445 remote network file systems
446 automatically pull in this
447 unit, and order themselves
448 after it. Note that networking
449 daemons that simply provide
450 functionality to other hosts
451 generally do not need to pull
456 <term><filename>paths.target</filename></term>
458 <para>A special target unit
459 that sets up all path units
461 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>
462 for details) that shall be
463 active after boot.</para>
465 <para>It is recommended that
466 path units installed by
467 applications get pulled in via
468 <varname>Wants=</varname>
469 dependencies from this
470 unit. This is best configured
472 <varname>WantedBy=paths.target</varname>
474 <literal>[Install]</literal>
479 <term><filename>poweroff.target</filename></term>
481 <para>A special target unit
482 for shutting down and powering off the system.</para>
484 <para>Applications wanting to
485 power off the system should start
488 <para><filename>runlevel0.target</filename>
489 is an alias for this target
490 unit, for compatibility with SysV.</para>
494 <term><filename>reboot.target</filename></term>
496 <para>A special target unit
497 for shutting down and rebooting the system.</para>
499 <para>Applications wanting to
500 reboot the system should start
503 <para><filename>runlevel6.target</filename>
504 is an alias for this target
505 unit, for compatibility with SysV.</para>
509 <term><filename>remote-fs.target</filename></term>
512 <filename>local-fs.target</filename>,
516 <para>systemd automatically
517 adds dependencies of type
518 <varname>After=</varname> for
519 this target unit to all SysV
520 init script service units with
521 an LSB header referring to the
522 <literal>$remote_fs</literal>
527 <term><filename>rescue.target</filename></term>
529 <para>A special target unit
530 for setting up the base system
531 and a rescue shell.</para>
533 <para><filename>runlevel1.target</filename>
534 is an alias for this target
535 unit, for compatibility with SysV.</para>
539 <term><filename>initrd-root-fs.target</filename></term>
541 <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry>
544 <varname>Before=</varname> to
546 <filename>sysroot.mount</filename>
547 unit, which is generated from
548 the kernel command line.
553 <term><filename>runlevel2.target</filename></term>
554 <term><filename>runlevel3.target</filename></term>
555 <term><filename>runlevel4.target</filename></term>
556 <term><filename>runlevel5.target</filename></term>
558 <para>These are targets that
559 are called whenever the SysV
560 compatibility code asks for
562 respectively. It is a good
563 idea to make this an alias for
565 <filename>multi-user.target</filename>
567 <filename>graphical.target</filename>
572 <term><filename>shutdown.target</filename></term>
574 <para>A special target unit
575 that terminates the services
576 on system shutdown.</para>
578 <para>Services that shall be
579 terminated on system shutdown
580 shall add <varname>Conflicts=</varname>
581 dependencies to this unit for
582 their service unit, which is
584 <varname>DefaultDependencies=yes</varname>
585 is set (the default).</para>
589 <term><filename>sigpwr.target</filename></term>
591 <para>A special target that is
592 started when systemd receives
593 the SIGPWR process signal,
594 which is normally sent by the
595 kernel or UPS daemons when
600 <term><filename>sleep.target</filename></term>
602 <para>A special target unit
604 <filename>suspend.target</filename>,
605 <filename>hibernate.target</filename>
607 <filename>hybrid-sleep.target</filename>
608 and may be used to hook units
614 <term><filename>sockets.target</filename></term>
616 <para>A special target unit
617 that sets up all socket
619 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
620 for details) that shall be
621 active after boot.</para>
623 <para>Services that can be
624 socket-activated shall add
625 <varname>Wants=</varname>
626 dependencies to this unit for
627 their socket unit during
628 installation. This is best
630 <varname>WantedBy=sockets.target</varname>
632 <literal>[Install]</literal>
637 <term><filename>suspend.target</filename></term>
639 <para>A special target unit
641 system. This pulls in
642 <filename>sleep.target</filename>.</para>
646 <term><filename>swap.target</filename></term>
649 <filename>local-fs.target</filename>, but for swap
655 <term><filename>sysinit.target</filename></term>
657 <para>A special target unit
658 covering early boot-up scripts.</para>
662 <term><filename>syslog.socket</filename></term>
664 <para>The socket unit
665 syslog implementations should
666 listen on. All userspace log
667 messages will be made
668 available on this socket. For
669 more information about syslog
670 integration, please consult
672 url="http://www.freedesktop.org/wiki/Software/systemd/syslog">Syslog
678 <term><filename>system-update.target</filename></term>
680 <para>A special target unit
681 that is used for off-line
683 <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
684 will redirect the boot process
686 <filename>/system-update</filename>
687 exists. For more information
689 url="http://freedesktop.org/wiki/Software/systemd/SystemUpdates">System
691 Specification</ulink>.</para>
695 <term><filename>timers.target</filename></term>
697 <para>A special target unit
698 that sets up all timer
700 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>
701 for details) that shall be
702 active after boot.</para>
704 <para>It is recommended that
705 timer units installed by
706 applications get pulled in via
707 <varname>Wants=</varname>
708 dependencies from this
709 unit. This is best configured
711 <varname>WantedBy=timers.target</varname>
713 <literal>[Install]</literal>
718 <term><filename>umount.target</filename></term>
720 <para>A special target unit
721 that umounts all mount and
722 automount points on system
725 <para>Mounts that shall be
726 unmounted on system shutdown
728 dependencies to this unit for
729 their mount unit, which is
731 <varname>DefaultDependencies=yes</varname>
732 is set (the default).</para>
740 <title>Special System Units for Devices</title>
742 <para>Some target units are automatically pulled in as
743 devices of certain kinds show up in the system. These
744 may be used to automatically activate various services
745 based on the specific type of the available
750 <term><filename>bluetooth.target</filename></term>
752 <para>This target is started
753 automatically as soon as a
754 Bluetooth controller is
755 plugged in or becomes
756 available at boot.</para>
758 <para>This may be used to pull
759 in Bluetooth management
760 daemons dynamically when
761 Bluetooth hardware is
766 <term><filename>printer.target</filename></term>
768 <para>This target is started
769 automatically as soon as a
770 printer is plugged in or
774 <para>This may be used to pull
775 in printer management
776 daemons dynamically when
782 <term><filename>smartcard.target</filename></term>
784 <para>This target is started
785 automatically as soon as a
786 smartcard controller is
787 plugged in or becomes
788 available at boot.</para>
790 <para>This may be used to pull
791 in smartcard management
792 daemons dynamically when
793 smartcard hardware is
798 <term><filename>sound.target</filename></term>
800 <para>This target is started
801 automatically as soon as a
802 sound card is plugged in or
806 <para>This may be used to pull
807 in audio management daemons
808 dynamically when audio
809 hardware is found.</para>
816 <title>Special Passive System Units </title>
818 <para>A number of special system targets are defined
819 that can be used to properly order boot-up of optional
820 services. These targets are generally not part of the
821 initial boot transaction, unless they are explicitly
822 pulled in by one of the implementing services. Note
823 specifically, that these <emphasis>passive</emphasis>
824 target units are generally not pulled in by the
825 consumer of a service, but by the provider of the
826 service. This means: a consuming service should order
827 itself after these targets (as appropriate), but not
828 pull it in. A providing service should order itself
829 before these targets (as appropriate) and pull it in
830 (via a <varname>Wants=</varname> type
833 <para>Note that these passive units cannot be started
834 manually, i.e. <literal>systemctl start
835 time-sync.target</literal> will fail with an
836 error. They can only be pulled in by dependency. This
837 is enforced since they exist for ordering purposes
838 only and thus are not useful as only unit within a
843 <term><filename>local-fs-pre.target</filename></term>
845 <para>This target unit is
846 automatically ordered before
847 all local mount points marked
848 with <option>auto</option>
849 (see above). It can be used to
850 execute certain units before
851 all local mounts.</para>
855 <term><filename>network.target</filename></term>
857 <para>This unit is supposed to
858 indicate when network
859 functionality is available,
860 but it is only very weakly
861 defined what that is supposed
862 to mean, with one exception:
863 at shutdown, a unit that is
865 <filename>network.target</filename>
866 will be stopped before the
867 network -- to whatever level
868 it might be set up then -- is
869 shut down. Also see <ulink
870 url="http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running
871 Services After the Network is
873 information. Also see
874 <filename>network-online.target</filename>
875 described above.</para>
877 <para>systemd automatically
878 adds dependencies of type
879 <varname>After=</varname> for
880 this target unit to all SysV
881 init script service units with
882 an LSB header referring to the
883 <literal>$network</literal>
889 <term><filename>nss-lookup.target</filename></term>
891 <para>A target that should be
892 used as synchronization point
893 for all host/network name
894 service lookups. Note that
895 this is independent of
896 user/group name lookups for
898 <filename>nss-user-lookup.target</filename>
899 should be used. systemd
902 <varname>After=</varname> for
903 this target unit to all SysV
904 init script service units with
905 an LSB header referring to the
906 <literal>$named</literal>
911 <term><filename>nss-user-lookup.target</filename></term>
913 <para>A target that should be
914 used as synchronization point
915 for all user/group name
916 service lookups. Note that
917 this is independent of
918 host/network name lookups for
920 <filename>nss-lookup.target</filename>
921 should be used. </para>
925 <term><filename>remote-fs-pre.target</filename></term>
927 <para>This target unit is
928 automatically ordered before
929 all remote mount point units
930 (see above). It can be used to
931 run certain units before the
933 established. Note that this
934 unit is generally not part of
935 the initial transaction,
936 unless the unit that wants to
937 be ordered before all remote
938 mounts pulls it in via a
939 <varname>Wants=</varname> type
940 dependency. If the unit wants
941 to be pulled in by the first
942 remote mount showing up it
944 <filename>network-online.target</filename>
947 <para>Again, this target unit
948 is <emphasis>not</emphasis>
949 suitable for pulling in other
950 units, it is only useful for
955 <term><filename>rpcbind.target</filename></term>
957 <para>systemd automatically
958 adds dependencies of type
959 <varname>After=</varname> for
960 this target unit to all SysV
961 init script service units with
962 an LSB header referring to the
963 <literal>$portmap</literal>
968 <term><filename>time-sync.target</filename></term>
970 <para>systemd automatically
971 adds dependencies of type
972 <varname>After=</varname> for
973 this target unit to all SysV
974 init script service units with
975 an LSB header referring to the
976 <literal>$time</literal>
984 <title>Special User Units</title>
986 <para>When systemd runs as a user instance, the
987 following special units are available, which have
988 similar definitions as their system counterparts:
989 <filename>default.target</filename>,
990 <filename>shutdown.target</filename>,
991 <filename>sockets.target</filename>,
992 <filename>timers.target</filename>,
993 <filename>paths.target</filename>,
994 <filename>bluetooth.target</filename>,
995 <filename>printer.target</filename>,
996 <filename>smartcard.target</filename>,
997 <filename>sound.target</filename>.</para>
999 <para>In addition the following special unit is
1000 understood only when systemd runs as service instance:</para>
1004 <term><filename>exit.target</filename></term>
1006 <para>A special service unit
1007 for shutting down the
1008 user service manager.</para>
1010 <para>Applications wanting to
1011 terminate the user service
1012 manager should start this
1013 unit. If systemd receives
1014 <constant>SIGTERM</constant> or <constant>SIGINT</constant> when running
1015 as user service daemon it will
1016 start this unit.</para>
1018 <para>Normally, this pulls in
1019 <filename>shutdown.target</filename>
1020 which in turn should be
1021 conflicted by all units that
1022 want to be shut down on
1023 user service manager exit.</para>
1030 <title>Special Slice Units</title>
1032 <para>There are four <literal>.slice</literal> units
1033 which form the basis of the hierarchy for assignment
1034 of resources for services, users, and virtual machines
1035 or containers.</para>
1039 <term><filename>-.slice</filename></term>
1041 <para>The root slice is the
1042 root of the hierarchy. It
1043 usually does not contain units
1044 directly, but may be used to
1045 set defaults for the whole
1051 <term><filename>system.slice</filename></term>
1053 <para>By default, all services
1055 <command>systemd</command> are
1056 found in this slice.</para>
1061 <term><filename>user.slice</filename></term>
1063 <para>By default, all user
1064 processes and services started
1065 on behalf of the user,
1066 including the per-user systemd
1067 instance are found in this
1073 <term><filename>machine.slice</filename></term>
1075 <para>By defalt, all virtual
1076 machines and containers
1078 <command>systemd-machined</command>
1079 are found in this slice.
1087 <title>See Also</title>
1089 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1090 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1091 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1092 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1093 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1094 <citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1095 <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1096 <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>