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