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