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