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