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