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>nss-lookup.target</filename>,
75 <filename>nss-user-lookup.target</filename>,
76 <filename>paths.target</filename>,
77 <filename>poweroff.target</filename>,
78 <filename>printer.target</filename>,
79 <filename>reboot.target</filename>,
80 <filename>remote-fs.target</filename>,
81 <filename>remote-fs-pre.target</filename>,
82 <filename>remote-fs-setup.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></para>
107 <title>Description</title>
109 <para>A few units are treated specially by
110 systemd. They have special internal semantics and
111 cannot be renamed.</para>
115 <title>Special System Units</title>
119 <term><filename>basic.target</filename></term>
121 <para>A special target unit
122 covering basic boot-up.</para>
123 <para>systemd automatically
124 adds dependencies of the types
125 <varname>Requires=</varname>
126 and <varname>After=</varname>
127 for this target unit to all
128 services (except for those
130 <varname>DefaultDependencies=no</varname>).</para>
132 <para>Usually this should
133 pull-in all mount points, swap
134 devices, sockets, timers, and
135 path units and other basic
136 initialization necessary for
142 <term><filename>ctrl-alt-del.target</filename></term>
144 <para>systemd starts this
146 Control+Alt+Del is pressed on
147 the console. Usually this
148 should be aliased (symlinked)
150 <filename>reboot.target</filename>.</para>
154 <term><filename>cryptsetup.target</filename></term>
156 <para>A target that pulls in
157 setup services for all
163 <term><filename>dbus.service</filename></term>
165 <para>A special unit for the
166 D-Bus bus daemon. As soon as
167 this service is fully started
168 up systemd will connect to it
174 <term><filename>dbus.socket</filename></term>
176 <para>A special unit for the
177 D-Bus system bus socket. All
179 <varname>Type=dbus</varname>
186 <term><filename>default.target</filename></term>
188 <para>The default unit systemd
189 starts at bootup. Usually this
190 should be aliased (symlinked)
192 <filename>multi-user.target</filename>
194 <filename>graphical.target</filename>.</para>
196 <para>The default unit systemd
197 starts at bootup can be
199 <varname>systemd.unit=</varname>
200 kernel command line option.</para>
204 <term><filename>display-manager.service</filename></term>
206 <para>The display manager
207 service. Usually this should
208 be aliased (symlinked) to
209 <filename>gdm.service</filename>
210 or a similar display manager
215 <term><filename>emergency.target</filename></term>
217 <para>A special target unit
218 that starts an emergency
220 console. This unit is supposed
221 to be used with the kernel
223 <varname>systemd.unit=</varname>
224 and has otherwise little use.
229 <term><filename>final.target</filename></term>
231 <para>A special target unit
232 that is used during the
233 shutdown logic and may be used
234 to pull in late services after
235 all normal services are
236 already terminated and all
242 <term><filename>getty.target</filename></term>
244 <para>A special target unit
245 that pulls in statically
247 <filename>getty</filename>
253 <term><filename>graphical.target</filename></term>
255 <para>A special target unit
256 for setting up a graphical
257 login screen. This pulls in
258 <filename>multi-user.target</filename>.</para>
260 <para>Units that are needed
261 for graphical logins shall add
262 <varname>Wants=</varname>
263 dependencies for their unit to
265 <filename>multi-user.target</filename>)
266 during installation. This is
268 <varname>WantedBy=graphical.target</varname>
270 <literal>[Install]</literal>
275 <term><filename>hibernate.target</filename></term>
277 <para>A special target unit
279 system. This pulls in
280 <filename>sleep.target</filename>.</para>
284 <term><filename>hybrid-sleep.target</filename></term>
286 <para>A special target unit
287 for hibernating and suspending the
288 system at the same time. This pulls in
289 <filename>sleep.target</filename>.</para>
293 <term><filename>halt.target</filename></term>
295 <para>A special target unit
296 for shutting down and halting
297 the system. Note that this
298 target is distinct from
299 <filename>poweroff.target</filename>
300 in that it generally really
301 just halts the system rather
302 than powering it down.</para>
304 <para>Applications wanting to
305 halt the system should start
310 <term><filename>initrd-fs.target</filename></term>
312 <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry>
315 <varname>Before=</varname> to
316 <filename>sysroot-usr.mount</filename>
317 and all mount points fround in
318 <filename>/etc/fstab</filename>
320 <option>auto</option> and
321 <option>x-initrd.mount</option>
327 <term><filename>kbrequest.target</filename></term>
329 <para>systemd starts this
330 target whenever Alt+ArrowUp is
331 pressed on the console. This
332 is a good candidate to be
333 aliased (symlinked) to
334 <filename>rescue.target</filename>.</para>
338 <term><filename>kexec.target</filename></term>
340 <para>A special target unit
341 for shutting down and rebooting the system via kexec.</para>
343 <para>Applications wanting to
344 reboot the system with kexec should start
349 <term><filename>local-fs.target</filename></term>
351 <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry>
354 <varname>Before=</varname> to
355 all mount units that refer to
356 local mount points for this
357 target unit. In addition, it
358 adds dependencies of type
359 <varname>Wants=</varname> to
360 this target unit for those
362 <filename>/etc/fstab</filename>
364 <option>auto</option> mount
369 <term><filename>multi-user.target</filename></term>
371 <para>A special target unit
372 for setting up a multi-user
373 system (non-graphical). This
375 <filename>graphical.target</filename>.</para>
377 <para>Units that are needed
378 for a multi-user system shall
379 add <varname>Wants=</varname>
380 dependencies for their unit to
382 installation. This is best
384 <varname>WantedBy=multi-uer.target</varname>
386 <literal>[Install]</literal>
391 <term><filename>network.target</filename></term>
393 <para>systemd automatically
394 adds dependencies of type
395 <varname>After=</varname> for
396 this target unit to all SysV
397 init script service units with
398 an LSB header referring to the
399 <literal>$network</literal>
402 <para>This unit is supposed to
403 indicate when the network is
404 "up", but it is only very
405 loosely defined what that is
406 supposed to mean. Also see <ulink
407 url="http://www.freedesktop.org/wiki/Software/systemd/NetworkTarget">Running
408 Services After the Network is
414 <term><filename>paths.target</filename></term>
416 <para>A special target unit
417 that sets up all path units
419 <citerefentry><refentrytitle>systemd.path</refentrytitle><manvolnum>5</manvolnum></citerefentry>
420 for details) that shall be
421 active after boot.</para>
423 <para>It is recommended that
424 path units installed by
425 applications get pulled in via
426 <varname>Wants=</varname>
427 dependencies from this
428 unit. This is best configured
430 <varname>WantedBy=paths.target</varname>
432 <literal>[Install]</literal>
437 <term><filename>poweroff.target</filename></term>
439 <para>A special target unit
440 for shutting down and powering off the system.</para>
442 <para>Applications wanting to
443 power off the system should start
446 <para><filename>runlevel0.target</filename>
447 is an alias for this target
448 unit, for compatibility with SysV.</para>
452 <term><filename>reboot.target</filename></term>
454 <para>A special target unit
455 for shutting down and rebooting the system.</para>
457 <para>Applications wanting to
458 reboot the system should start
461 <para><filename>runlevel6.target</filename>
462 is an alias for this target
463 unit, for compatibility with SysV.</para>
467 <term><filename>remote-fs.target</filename></term>
470 <filename>local-fs.target</filename>,
474 <para>systemd automatically
475 adds dependencies of type
476 <varname>After=</varname> for
477 this target unit to all SysV
478 init script service units with
479 an LSB header referring to the
480 <literal>$remote_fs</literal>
485 <term><filename>remote-fs-setup.target</filename></term>
487 <para>This target unit is
488 automatically pulled in (by a
489 <varname>Wants=</varname> type
490 dependency) by all remote
491 mount points. It can be used
492 to run certain units when at
493 least one remote file system
494 is to be mounted. Note that
495 this target is not ordered
496 against the remote mounts, use
497 <filename>remote-fs-pre.target</filename>
498 for that (see below).</para>
500 <para>Again, this target unit
501 is <emphasis>not</emphasis>
502 suitable for ordering, it is
503 only useful for pulling in
508 <term><filename>rescue.target</filename></term>
510 <para>A special target unit
511 for setting up the base system
512 and a rescue shell.</para>
514 <para><filename>runlevel1.target</filename>
515 is an alias for this target
516 unit, for compatibility with SysV.</para>
520 <term><filename>initrd-root-fs.target</filename></term>
522 <para><citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>3</manvolnum></citerefentry>
525 <varname>Before=</varname> to
527 <filename>sysroot.mount</filename>
528 unit, which is generated from
529 the kernel command line.
534 <term><filename>runlevel2.target</filename></term>
535 <term><filename>runlevel3.target</filename></term>
536 <term><filename>runlevel4.target</filename></term>
537 <term><filename>runlevel5.target</filename></term>
539 <para>These are targets that
540 are called whenever the SysV
541 compatibility code asks for
543 respectively. It is a good
544 idea to make this an alias for
546 <filename>multi-user.target</filename>
548 <filename>graphical.target</filename>
553 <term><filename>shutdown.target</filename></term>
555 <para>A special target unit
556 that terminates the services
557 on system shutdown.</para>
559 <para>Services that shall be
560 terminated on system shutdown
561 shall add <varname>Conflicts=</varname>
562 dependencies to this unit for
563 their service unit, which is
565 <varname>DefaultDependencies=yes</varname>
566 is set (the default).</para>
570 <term><filename>sigpwr.target</filename></term>
572 <para>A special target that is
573 started when systemd receives
574 the SIGPWR process signal,
575 which is normally sent by the
576 kernel or UPS daemons when
581 <term><filename>sleep.target</filename></term>
583 <para>A special target unit
585 <filename>suspend.target</filename>,
586 <filename>hibernate.target</filename>
588 <filename>hybrid-sleep.target</filename>
589 and may be used to hook units
595 <term><filename>sockets.target</filename></term>
597 <para>A special target unit
598 that sets up all socket
600 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>
601 for details) that shall be
602 active after boot.</para>
604 <para>Services that can be
605 socket-activated shall add
606 <varname>Wants=</varname>
607 dependencies to this unit for
608 their socket unit during
609 installation. This is best
611 <varname>WantedBy=sockets.target</varname>
613 <literal>[Install]</literal>
618 <term><filename>suspend.target</filename></term>
620 <para>A special target unit
622 system. This pulls in
623 <filename>sleep.target</filename>.</para>
627 <term><filename>swap.target</filename></term>
630 <filename>local-fs.target</filename>, but for swap
636 <term><filename>sysinit.target</filename></term>
638 <para>A special target unit
639 covering early boot-up scripts.</para>
643 <term><filename>syslog.socket</filename></term>
645 <para>The socket unit
646 syslog implementations should
647 listen on. All userspace log
648 messages will be made
649 available on this socket. For
650 more information about syslog
651 integration, please consult
653 url="http://www.freedesktop.org/wiki/Software/systemd/syslog">Syslog
659 <term><filename>system-update.target</filename></term>
661 <para>A special target unit
662 that is used for off-line
664 <citerefentry><refentrytitle>systemd-system-update-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
665 will redirect the boot process
667 <filename>/system-update</filename>
668 exists. For more information
670 url="http://freedesktop.org/wiki/Software/systemd/SystemUpdates">System
672 Specification</ulink>.</para>
676 <term><filename>timers.target</filename></term>
678 <para>A special target unit
679 that sets up all timer
681 <citerefentry><refentrytitle>systemd.timer</refentrytitle><manvolnum>5</manvolnum></citerefentry>
682 for details) that shall be
683 active after boot.</para>
685 <para>It is recommended that
686 timer units installed by
687 applications get pulled in via
688 <varname>Wants=</varname>
689 dependencies from this
690 unit. This is best configured
692 <varname>WantedBy=timers.target</varname>
694 <literal>[Install]</literal>
699 <term><filename>umount.target</filename></term>
701 <para>A special target unit
702 that umounts all mount and
703 automount points on system
706 <para>Mounts that shall be
707 unmounted on system shutdown
709 dependencies to this unit for
710 their mount unit, which is
712 <varname>DefaultDependencies=yes</varname>
713 is set (the default).</para>
721 <title>Special System Units for Devices</title>
723 <para>Some target units are automatically pulled in as
724 devices of certain kinds show up in the system. These
725 may be used to automatically activate various services
726 based on the specific type of the available
731 <term><filename>bluetooth.target</filename></term>
733 <para>This target is started
734 automatically as soon as a
735 Bluetooth controller is
736 plugged in or becomes
737 available at boot.</para>
739 <para>This may be used to pull
740 in Bluetooth management
741 daemons dynamically when
742 Bluetooth hardware is
747 <term><filename>printer.target</filename></term>
749 <para>This target is started
750 automatically as soon as a
751 printer is plugged in or
755 <para>This may be used to pull
756 in printer management
757 daemons dynamically when
763 <term><filename>smartcard.target</filename></term>
765 <para>This target is started
766 automatically as soon as a
767 smartcard controller is
768 plugged in or becomes
769 available at boot.</para>
771 <para>This may be used to pull
772 in printer management
773 daemons dynamically when
774 smartcard hardware is
779 <term><filename>sound.target</filename></term>
781 <para>This target is started
782 automatically as soon as a
783 sound card is plugged in or
787 <para>This may be used to pull
788 in audio management daemons
789 dynamically when printer
790 hardware is found.</para>
797 <title>Special Passive System Units </title>
799 <para>A number of special system targets are defined
800 that can be used to properly order boot-up of optional
801 services. These targets are generally not part of the
802 initial boot transaction, unless they are explicitly
803 pulled in by one of the implementing services. Note
804 specifically, that these <emphasis>passive</emphasis>
805 target units are generally not pulled in by the
806 consumer of a service, but by the provider of the
807 service. This means: a consuming service should order
808 itself after these targets (as appropriate), but not
809 pull it in. A providing service should order itself
810 before these targets (as appropriate) and pull it in
811 (via a <varname>Wants=</varname> type
816 <term><filename>local-fs-pre.target</filename></term>
818 <para>This target unit is
819 automatically ordered before
820 all local mount points marked
821 with <option>auto</option>
822 (see above). It can be used to
823 execute certain units before
824 all local mounts.</para>
828 <term><filename>nss-lookup.target</filename></term>
830 <para>A target that should be
831 used as synchronization point
832 for all host/network name
833 service lookups. Note that
834 this is independent of
835 user/group name lookups for
837 <filename>nss-user-lookup.target</filename>
838 should be used. systemd
841 <varname>After=</varname> for
842 this target unit to all SysV
843 init script service units with
844 an LSB header referring to the
845 <literal>$named</literal>
850 <term><filename>nss-user-lookup.target</filename></term>
852 <para>A target that should be
853 used as synchronization point
854 for all user/group name
855 service lookups. Note that
856 this is independent of
857 host/network name lookups for
859 <filename>nss-lookup.target</filename>
860 should be used. </para>
864 <term><filename>remote-fs-pre.target</filename></term>
866 <para>This target unit is
867 automatically ordered before
868 all remote mount point units
869 (see above). It can be used to
870 run certain units before the
872 established. Note that this
873 unit is generally not part of
874 the initial transaction,
875 unless the unit that wants to
876 be ordered before all remote
877 mounts pulls it in via a
878 <varname>Wants=</varname> type
879 dependency. If the unit wants
880 to be pulled in by the first
881 remote mount showing up it
883 <filename>remote-fs-setup.target</filename>
886 <para>Again, this target unit
887 is <emphasis>not</emphasis>
888 suitable for pulling in other
889 units, it is only useful for
894 <term><filename>rpcbind.target</filename></term>
896 <para>systemd automatically
897 adds dependencies of type
898 <varname>After=</varname> for
899 this target unit to all SysV
900 init script service units with
901 an LSB header referring to the
902 <literal>$portmap</literal>
907 <term><filename>time-sync.target</filename></term>
909 <para>systemd automatically
910 adds dependencies of type
911 <varname>After=</varname> for
912 this target unit to all SysV
913 init script service units with
914 an LSB header referring to the
915 <literal>$time</literal>
923 <title>Special User Units</title>
925 <para>When systemd runs as a user instance, the
926 following special units are available, which have
927 similar definitions as their system counterparts:
928 <filename>default.target</filename>,
929 <filename>shutdown.target</filename>,
930 <filename>sockets.target</filename>,
931 <filename>timers.target</filename>,
932 <filename>paths.target</filename>,
933 <filename>bluetooth.target</filename>,
934 <filename>printer.target</filename>,
935 <filename>smartcard.target</filename>,
936 <filename>sound.target</filename>.</para>
938 <para>In addition the following special unit is
939 understood only when systemd runs as service instance:</para>
943 <term><filename>exit.target</filename></term>
945 <para>A special service unit
946 for shutting down the
947 user service manager.</para>
949 <para>Applications wanting to
950 terminate the user service
951 manager should start this
952 unit. If systemd receives
953 SIGTERM or SIGINT when running
954 as user service daemon it will
955 start this unit.</para>
957 <para>Normally, this pulls in
958 <filename>shutdown.target</filename>
959 which in turn should be
960 conflicted by all units that
961 want to be shut down on
962 user service manager exit.</para>
969 <title>See Also</title>
971 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
972 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
973 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
974 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
975 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
976 <citerefentry><refentrytitle>bootup</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
977 <citerefentry><refentrytitle>systemd-fstab-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>