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