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