]> git.ipfire.org Git - thirdparty/systemd.git/blob - man/systemd.special.xml
man: update documentation of special units
[thirdparty/systemd.git] / man / systemd.special.xml
1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <!--
6 This file is part of systemd.
7
8 Copyright 2010 Lennart Poettering
9
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU General Public License as published by
12 the Free Software Foundation; either version 2 of the License, or
13 (at your option) any later version.
14
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 General Public License for more details.
19
20 You should have received a copy of the GNU General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="systemd.special">
25
26 <refentryinfo>
27 <title>systemd.special</title>
28 <productname>systemd</productname>
29
30 <authorgroup>
31 <author>
32 <contrib>Developer</contrib>
33 <firstname>Lennart</firstname>
34 <surname>Poettering</surname>
35 <email>lennart@poettering.net</email>
36 </author>
37 </authorgroup>
38 </refentryinfo>
39
40 <refmeta>
41 <refentrytitle>systemd.special</refentrytitle>
42 <manvolnum>7</manvolnum>
43 </refmeta>
44
45 <refnamediv>
46 <refname>systemd.special</refname>
47 <refpurpose>Special systemd units</refpurpose>
48 </refnamediv>
49
50 <refsynopsisdiv>
51 <para><filename>basic.target</filename>,
52 <filename>ctrl-alt-del.target</filename>,
53 <filename>dbus.service</filename>,
54 <filename>dbus.socket</filename>,
55 <filename>default.target</filename>,
56 <filename>display-manager.service</filename>,
57 <filename>emergency.target</filename>,
58 <filename>exit.service</filename>,
59 <filename>final.service</filename>,
60 <filename>graphical.target</filename>,
61 <filename>http-daemon.target</filename>,
62 <filename>halt.target</filename>,
63 <filename>kbrequest.target</filename>,
64 <filename>kexec.target</filename>,
65 <filename>local-fs.target</filename>,
66 <filename>local-fs-pre.target</filename>,
67 <filename>mail-transfer-agent.target</filename>,
68 <filename>multi-user.target</filename>,
69 <filename>network.target</filename>,
70 <filename>nss-lookup.target</filename>,
71 <filename>poweroff.target</filename>,
72 <filename>reboot.target</filename>,
73 <filename>remote-fs.target</filename>,
74 <filename>remote-fs-pre.target</filename>,
75 <filename>rescue.target</filename>,
76 <filename>rpcbind.target</filename>,
77 <filename>runlevel2.target</filename>,
78 <filename>runlevel3.target</filename>,
79 <filename>runlevel4.target</filename>,
80 <filename>runlevel5.target</filename>,
81 <filename>shutdown.target</filename>,
82 <filename>sigpwr.target</filename>,
83 <filename>sockets.target</filename>,
84 <filename>swap.target</filename>,
85 <filename>sysinit.target</filename>,
86 <filename>syslog.service</filename>,
87 <filename>syslog.socket</filename>,
88 <filename>syslog.target</filename>,
89 <filename>time-sync.target</filename>,
90 <filename>umount.target</filename></para>
91 </refsynopsisdiv>
92
93 <refsect1>
94 <title>Description</title>
95
96 <para>A few units are treated specially by
97 systemd. They have special internal semantics and
98 cannot be renamed.</para>
99 </refsect1>
100
101 <refsect1>
102 <title>Special System Units</title>
103
104 <variablelist>
105 <varlistentry>
106 <term><filename>basic.target</filename></term>
107 <listitem>
108 <para>A special target unit
109 covering early boot-up.</para>
110 <para>systemd automatically
111 adds dependencies of the types
112 Requires and After for this
113 target unit to all SysV
114 service units configured for
115 runlevel 1 to 5.</para>
116 <para>Usually this should pull-in
117 all sockets, mount points,
118 swap devices and other basic
119 initialization necessary for
120 the general purpose
121 daemons. Most normal daemons
122 should have dependencies of
123 type After and Requires on
124 this unit.</para>
125 </listitem>
126 </varlistentry>
127 <varlistentry>
128 <term><filename>ctrl-alt-del.target</filename></term>
129 <listitem>
130 <para>systemd starts this
131 target whenever
132 Control+Alt+Del is pressed on
133 the console. Usually this
134 should be aliased (symlinked)
135 to
136 <filename>reboot.target</filename>.</para>
137 </listitem>
138 </varlistentry>
139 <varlistentry>
140 <term><filename>dbus.service</filename></term>
141 <listitem>
142 <para>A special unit for the
143 D-Bus system bus. As soon as
144 this service is fully started
145 up systemd will connect to it
146 and register its
147 service.</para>
148 </listitem>
149 </varlistentry>
150 <varlistentry>
151 <term><filename>dbus.socket</filename></term>
152 <listitem>
153 <para>A special unit for the
154 D-Bus system bus socket. All
155 units with
156 <literal>Type=dbus</literal>
157 automatically gain a
158 dependency on this
159 unit.</para>
160 </listitem>
161 </varlistentry>
162 <varlistentry>
163 <term><filename>default.target</filename></term>
164 <listitem>
165 <para>The default unit systemd
166 starts at bootup. Usually this
167 should be aliased (symlinked)
168 to
169 <filename>multi-user.target</filename>
170 or
171 <filename>graphical.target</filename>.</para>
172 <para>The default unit systemd
173 starts at bootup can be
174 overridden with the
175 <varname>systemd.unit=</varname>
176 kernel command line option.</para>
177 </listitem>
178 </varlistentry>
179 <varlistentry>
180 <term><filename>display-manager.service</filename></term>
181 <listitem>
182 <para>The display manager
183 service. Usually this should
184 be aliased (symlinked) to
185 <filename>gdm.service</filename>
186 or a similar display manager
187 service.</para>
188 <para>systemd automatically
189 adds dependencies of type
190 After for this target unit to
191 all SysV init script service
192 units with a LSB header
193 referring to the
194 <literal>$x-display-manager</literal>
195 facility, for compatibility
196 with Debian.</para>
197 </listitem>
198 </varlistentry>
199 <varlistentry>
200 <term><filename>emergency.target</filename></term>
201 <listitem>
202 <para>A special target unit
203 that starts an emergency
204 shell on the main
205 console. This unit is supposed
206 to be used with the kernel
207 command line option
208 <varname>systemd.unit=</varname>
209 and has otherwise little use.
210 </para>
211 </listitem>
212 </varlistentry>
213 <varlistentry>
214 <term><filename>final.target</filename></term>
215 <listitem>
216 <para>A special target unit
217 that is used during the
218 shutdown logic and may be used
219 to pull in late services after
220 all normal services are
221 already terminated and all
222 mounts unmounted.
223 </para>
224 </listitem>
225 </varlistentry>
226 <varlistentry>
227 <term><filename>graphical.target</filename></term>
228 <listitem>
229 <para>A special target unit
230 for setting up a graphical
231 login screen. This pulls in
232 <filename>multi-user.target</filename>.</para>
233
234 <para>Units that are needed
235 for graphical login shall add
236 Wants dependencies for their
237 unit to this unit (or
238 <filename>multi-user.target</filename>)
239 during installation.</para>
240 </listitem>
241 </varlistentry>
242 <varlistentry>
243 <term><filename>http-daemon.target</filename></term>
244 <listitem>
245 <para>A target for pulling in
246 an HTTP server if there is
247 any.</para>
248 <para>systemd automatically
249 adds dependencies of type
250 After for this target unit to
251 all SysV init script service
252 units with a LSB header
253 referring to the
254 <literal>$httpd</literal>
255 facility.</para>
256 </listitem>
257 </varlistentry>
258 <varlistentry>
259 <term><filename>halt.target</filename></term>
260 <listitem>
261 <para>A special target unit
262 for shutting down and halting the system.</para>
263
264 <para>Applications wanting to
265 halt the system should start
266 this unit.</para>
267 </listitem>
268 </varlistentry>
269 <varlistentry>
270 <term><filename>kbrequest.target</filename></term>
271 <listitem>
272 <para>systemd starts this
273 target whenever Alt+ArrowUp is
274 pressed on the console. This
275 is a good candidate to be
276 aliased (symlinked) to
277 <filename>rescue.target</filename>.</para>
278 </listitem>
279 </varlistentry>
280 <varlistentry>
281 <term><filename>kexec.target</filename></term>
282 <listitem>
283 <para>A special target unit
284 for shutting down and rebooting the system via kexec.</para>
285
286 <para>Applications wanting to
287 reboot the system with kexec should start
288 this unit.</para>
289 </listitem>
290 </varlistentry>
291 <varlistentry>
292 <term><filename>local-fs.target</filename></term>
293 <listitem>
294 <para>systemd automatically
295 adds dependencies of type
296 After to all mount units that
297 refer to local mount points
298 for this target unit. In
299 addition, systemd adds
300 dependencies of type Wants to
301 this target unit for those
302 mounts listed in
303 <filename>/etc/fstab</filename>
304 that have the
305 <option>auto</option> and
306 <option>comment=systemd.mount</option>
307 mount options set.</para>
308
309 <para>systemd automatically
310 adds dependencies of type
311 After for this target unit to
312 all SysV init script service
313 units with an LSB header
314 referring to the
315 <literal>$local_fs</literal>
316 facility.</para>
317 </listitem>
318 </varlistentry>
319 <varlistentry>
320 <term><filename>local-fs-pre.target</filename></term>
321 <listitem>
322 <para>This target unit is
323 automatically ordered before
324 all local mount points marked
325 with <option>auto</option>
326 (see above). It can be used to
327 execute certain units before
328 all local mounts.</para>
329 </listitem>
330 </varlistentry>
331 <varlistentry>
332 <term><filename>mail-transfer-agent.target</filename></term>
333 <listitem>
334 <para>The mail transfer agent
335 (MTA) service. Usually this
336 should pull-in all units
337 necessary for
338 sending/receiving mails on the
339 local host.</para>
340
341 <para>systemd automatically
342 adds dependencies of type
343 After for this target unit to
344 all SysV init script service
345 units with an LSB header
346 referring to the
347 <literal>$mail-transfer-agent</literal>
348 or
349 <literal>$mail-transport-agent</literal>
350 facilities, for compatibility
351 with Debian.</para>
352 </listitem>
353 </varlistentry>
354 <varlistentry>
355 <term><filename>multi-user.target</filename></term>
356 <listitem>
357 <para>A special target unit
358 for setting up a multi-user
359 system (non-graphical). This
360 is pulled in by
361 <filename>graphical.target</filename>.</para>
362
363 <para>Units that are needed
364 for a multi-user system shall
365 add Wants dependencies to
366 this unit for their unit during
367 installation.</para>
368 </listitem>
369 </varlistentry>
370 <varlistentry>
371 <term><filename>network.target</filename></term>
372 <listitem>
373 <para>systemd automatically
374 adds dependencies of type
375 After for this target unit to
376 all SysV init script service
377 units with an LSB header
378 referring to the
379 <literal>$network</literal>
380 facility.</para>
381 </listitem>
382 </varlistentry>
383 <varlistentry>
384 <term><filename>nss-lookup.target</filename></term>
385 <listitem>
386 <para>systemd automatically
387 adds dependencies of type
388 After for this target unit to
389 all SysV init script service
390 units with an LSB header
391 referring to the
392 <literal>$named</literal>
393 facility.</para>
394 </listitem>
395 </varlistentry>
396 <varlistentry>
397 <term><filename>poweroff.target</filename></term>
398 <listitem>
399 <para>A special target unit
400 for shutting down and powering off the system.</para>
401
402 <para>Applications wanting to
403 power off the system should start
404 this unit.</para>
405
406 <para><filename>runlevel0.target</filename>
407 is an alias for this target
408 unit, for compatibility with SysV.</para>
409 </listitem>
410 </varlistentry>
411 <varlistentry>
412 <term><filename>reboot.target</filename></term>
413 <listitem>
414 <para>A special target unit
415 for shutting down and rebooting the system.</para>
416
417 <para>Applications wanting to
418 reboot the system should start
419 this unit.</para>
420
421 <para><filename>runlevel6.target</filename>
422 is an alias for this target
423 unit, for compatibility with SysV.</para>
424 </listitem>
425 </varlistentry>
426 <varlistentry>
427 <term><filename>remote-fs.target</filename></term>
428 <listitem>
429 <para>Similar to
430 <filename>local-fs.target</filename>,
431 but for remote mount
432 points.</para>
433
434 <para>systemd automatically
435 adds dependencies of type
436 After for this target unit to
437 all SysV init script service
438 units with an LSB header
439 referring to the
440 <literal>$remote_fs</literal>
441 facility.</para>
442 </listitem>
443 </varlistentry>
444 <varlistentry>
445 <term><filename>remote-fs-pre.target</filename></term>
446 <listitem>
447 <para>This target unit is
448 automatically ordered before
449 all remote mount points marked
450 with <option>auto</option>
451 (see above). It can be used to
452 execute certain units before
453 all remote mounts.</para>
454 </listitem>
455 </varlistentry>
456 <varlistentry>
457 <term><filename>rescue.target</filename></term>
458 <listitem>
459 <para>A special target unit
460 for setting up the base system
461 and a rescue shell.</para>
462
463 <para><filename>runlevel1.target</filename>
464 is an alias for this target
465 unit, for compatibility with SysV.</para>
466 </listitem>
467 </varlistentry>
468 <varlistentry>
469 <term><filename>rpcbind.target</filename></term>
470 <listitem>
471 <para>systemd automatically
472 adds dependencies of type
473 After for this target unit to
474 all SysV init script service
475 units with an LSB header
476 referring to the
477 <literal>$rpcbind</literal>
478 facility.</para>
479 </listitem>
480 </varlistentry>
481 <varlistentry>
482 <term><filename>runlevel2.target</filename></term>
483 <listitem>
484 <para>This is a target that is
485 called whenever the SysV
486 compatibility code asks for
487 runlevel 2. It is a good idea
488 to make this an alias for
489 (i.e. symlink to)
490 <filename>multi-user.target</filename>.</para>
491 </listitem>
492 </varlistentry>
493 <varlistentry>
494 <term><filename>runlevel3.target</filename></term>
495 <listitem>
496 <para>This is a target that is
497 called whenever the SysV
498 compatibility code asks for
499 runlevel 3. It is a good idea
500 to make this an alias for
501 (i.e. symlink to)
502 <filename>multi-user.target</filename>
503 or
504 <filename>graphical.target</filename>.</para>
505 </listitem>
506 </varlistentry>
507 <varlistentry>
508 <term><filename>runlevel4.target</filename></term>
509 <listitem>
510 <para>This is a target that is
511 called whenever the SysV
512 compatibility code asks for
513 runlevel 4. It is a good idea
514 to make this an alias for
515 (i.e. symlink to)
516 <filename>multi-user.target</filename>
517 or
518 <filename>graphical.target</filename>.</para>
519 </listitem>
520 </varlistentry>
521 <varlistentry>
522 <term><filename>runlevel5.target</filename></term>
523 <listitem>
524 <para>This is a target that is
525 called whenever the SysV
526 compatibility code asks for
527 runlevel 5. It is a good idea
528 to make this an alias for
529 (i.e. symlink to)
530 <filename>multi-user.target</filename>
531 or
532 <filename>graphical.target</filename>.</para>
533 </listitem>
534 </varlistentry>
535 <varlistentry>
536 <term><filename>shutdown.target</filename></term>
537 <listitem>
538 <para>A special target unit
539 that terminates the services
540 on system shutdown.</para>
541
542 <para>Services that shall be
543 terminated on system shutdown
544 shall add Conflicts
545 dependencies to this unit for
546 their service unit, which is
547 implicitly done when
548 <varname>DefaultDependencies=yes</varname>
549 is set (the default).</para>
550
551 <para>systemd automatically
552 adds dependencies of type
553 Conflicts to this target unit
554 for all SysV init script
555 service units that shall be
556 terminated in SysV runlevels 0
557 or 6.</para>
558 </listitem>
559 </varlistentry>
560 <varlistentry>
561 <term><filename>sigpwr.target</filename></term>
562 <listitem>
563 <para>A special target that is
564 started when systemd receives
565 the SIGPWR process signal,
566 which is normally sent by the
567 kernel or UPS daemons when
568 power fails.</para>
569 </listitem>
570 </varlistentry>
571 <varlistentry>
572 <term><filename>sockets.target</filename></term>
573 <listitem>
574 <para>A special target unit
575 that sets up all service
576 sockets.</para>
577
578 <para>Services that can be
579 socket-activated shall add
580 Wants dependencies to this
581 unit for their socket unit
582 during installation.</para>
583 </listitem>
584 </varlistentry>
585 <varlistentry>
586 <term><filename>swap.target</filename></term>
587 <listitem>
588 <para>Similar to
589 <filename>local-fs.target</filename>, but for swap
590 partitions and swap
591 files.</para>
592 </listitem>
593 </varlistentry>
594 <varlistentry>
595 <term><filename>sysinit.target</filename></term>
596 <listitem>
597 <para>A special target unit
598 covering early boot-up scripts.</para>
599 <para>systemd automatically
600 adds dependencies of the types
601 Wants and After for all
602 SysV service units configured
603 for runlevels that are not 0
604 to 6 to this target unit.
605 This covers the special
606 boot-up runlevels some
607 distributions have, such as S
608 or b.</para>
609 </listitem>
610 </varlistentry>
611 <varlistentry>
612 <term><filename>syslog.service</filename></term>
613 <listitem>
614 <para>The syslog service if
615 any. Implementations should
616 create a symlink from the
617 actual syslog implementation
618 to this generic name for
619 activating it.</para>
620 </listitem>
621 </varlistentry>
622 <varlistentry>
623 <term><filename>syslog.socket</filename></term>
624 <listitem>
625 <para>The socket unit where
626 syslog implementations should
627 listen on. All userspace log
628 messages will be made
629 available on this
630 socket.</para>
631 </listitem>
632 </varlistentry>
633 <varlistentry>
634 <term><filename>syslog.target</filename></term>
635 <listitem>
636 <para>systemd automatically
637 adds dependencies of type
638 After for this target unit to
639 all SysV init script service
640 units with an LSB header
641 referring to the
642 <literal>$syslog</literal>
643 facility.</para>
644 </listitem>
645 </varlistentry>
646 <varlistentry>
647 <term><filename>time-sync.target</filename></term>
648 <listitem>
649 <para>systemd automatically
650 adds dependencies of type
651 After for this target unit to
652 all SysV init script service
653 units with an LSB header
654 referring to the
655 <literal>$time</literal>
656 facility.</para>
657 </listitem>
658 </varlistentry>
659 <varlistentry>
660 <term><filename>umount.target</filename></term>
661 <listitem>
662 <para>A special target unit
663 that umounts all mount and
664 automount points on system
665 shutdown.</para>
666
667 <para>Mounts that shall be
668 unmounted on system shutdown
669 shall add Conflicts
670 dependencies to this unit for
671 their mount unit, which is
672 implicitly done when
673 <varname>DefaultDependencies=yes</varname>
674 is set (the default).</para>
675 </listitem>
676 </varlistentry>
677 </variablelist>
678 </refsect1>
679
680 <refsect1>
681 <title>Special User Units</title>
682
683 <para>When systemd runs as a user instance, the
684 following special units are available, which have
685 similar definitions as their system counterparts:
686 <filename>default.target</filename>,
687 <filename>shutdown.target</filename>,
688 <filename>sockets.target</filename></para>
689
690 <para>In addition the following special unit is
691 understood only when systemd runs as service instance:</para>
692
693 <variablelist>
694 <varlistentry>
695 <term><filename>exit.service</filename></term>
696 <listitem>
697 <para>A special service unit
698 for shutting down the
699 user service manager.</para>
700
701 <para>Applications wanting to
702 terminate the user service
703 manager should start this
704 unit. If systemd receives
705 SIGTERM or SIGINT when running
706 as user service daemon it will
707 start this unit.</para>
708
709 <para>Normally, this pulls in
710 <filename>shutdown.target</filename>
711 which in turn should be
712 conflicted by all units that
713 want to be shut down on
714 user service manager exit.</para>
715 </listitem>
716 </varlistentry>
717 </variablelist>
718 </refsect1>
719
720 <refsect1>
721 <title>See Also</title>
722 <para>
723 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
724 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
725 <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
726 <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
727 <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>
728 </para>
729 </refsect1>
730
731 </refentry>