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