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