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