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