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