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