man/systemd.xml

   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">
  25
  26         <refentryinfo>
  27                 <title>systemd</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</refentrytitle>
  42                 <manvolnum>1</manvolnum>
  43         </refmeta>
  44
  45         <refnamediv>
  46                 <refname>systemd</refname>
  47                 <refpurpose>systemd System and Session Manager</refpurpose>
  48         </refnamediv>
  49
  50         <refsynopsisdiv>
  51                 <cmdsynopsis>
  52                         <command>systemd <arg choice="opt" rep="repeat">OPTIONS</arg></command>
  53                 </cmdsynopsis>
  54                 <cmdsynopsis>
  55                         <command>init <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg></command>
  56                 </cmdsynopsis>
  57         </refsynopsisdiv>
  58
  59         <refsect1>
  60                 <title>Description</title>
  61
  62                 <para>systemd is a system and session manager for
  63                 Linux operating systems. When run as first process on
  64                 boot (as PID 1) it may act as init system that brings
  65                 up and maintains userspace.</para>
  66
  67                 <para>For compatibility with SysV if systemd is called
  68                 as <command>init</command> and a PID that is not
  69                 1 it will execute <command>telinit</command> and pass
  70                 all command line arguments unmodified. That means
  71                 <command>init</command> and <command>telinit</command>
  72                 are mostly equivalent when invoked from normal login sessions. See
  73                 <citerefentry><refentrytitle>telinit</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  74                 for more information.</para>
  75         </refsect1>
  76
  77         <refsect1>
  78                 <title>Options</title>
  79
  80                 <para>The following options are understood:</para>
  81
  82                 <variablelist>
  83                         <varlistentry>
  84                                 <term><option>-h</option></term>
  85                                 <term><option>--help</option></term>
  86
  87                                 <listitem><para>Prints a short help
  88                                 text and exits.</para></listitem>
  89                         </varlistentry>
  90                         <varlistentry>
  91                                 <term><option>--unit=</option></term>
  92
  93                                 <listitem><para>Set default unit to
  94                                 activate on startup. If not specified
  95                                 defaults to
  96                                 <filename>default.target</filename>.</para></listitem>
  97                         </varlistentry>
  98                         <varlistentry>
  99                                 <term><option>--running-as=</option></term>
 100
 101                                 <listitem><para>Tell systemd to run in
 102                                 a particular mode. Argument is one of
 103                                 <option>system</option>,
 104                                 <option>session</option>. Normally it
 105                                 should not be necessary to pass this
 106                                 option, as systemd automatically
 107                                 detects the mode it is started
 108                                 in. This call is hence of little use
 109                                 except for
 110                                 debugging.</para></listitem>
 111                         </varlistentry>
 112                         <varlistentry>
 113                                 <term><option>--test</option></term>
 114
 115                                 <listitem><para>Determine startup
 116                                 sequence, dump it and exit. This is an
 117                                 option useful for debugging
 118                                 only.</para></listitem>
 119                         </varlistentry>
 120                         <varlistentry>
 121                                 <term><option>--dump-configuration-items</option></term>
 122
 123                                 <listitem><para>Dump understood unit
 124                                 configuration items. This outputs a
 125                                 terse but complete list of
 126                                 configuration items understood in unit
 127                                 definition files.</para></listitem>
 128                         </varlistentry>
 129                         <varlistentry>
 130                                 <term><option>--confirm-spawn</option></term>
 131
 132                                 <listitem><para>Ask for confirmation when spawning processes.</para></listitem>
 133                         </varlistentry>
 134                         <varlistentry>
 135                                 <term><option>--introspect=</option></term>
 136
 137                                 <listitem><para>Extract D-Bus
 138                                 interface introspection data. This is
 139                                 mostly useful at build ot install time
 140                                 to generate data suitable for the
 141                                 D-Bus interfaces
 142                                 repository. Optionally the interface
 143                                 name for the introspection data may be
 144                                 specified. If omitted the
 145                                 introspection data for all interfaces
 146                                 is dumped.</para></listitem>
 147                         </varlistentry>
 148                         <varlistentry>
 149                                 <term><option>--log-level=</option></term>
 150
 151                                 <listitem><para>Set log level. As
 152                                 argument this accepts a numerical log
 153                                 level or the well-known <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 154                                 symbolic names (lowercase):
 155                                 <option>emerg</option>,
 156                                 <option>alert</option>,
 157                                 <option>crit</option>,
 158                                 <option>err</option>,
 159                                 <option>warning</option>,
 160                                 <option>notice</option>,
 161                                 <option>info</option>,
 162                                 <option>debug</option>.</para></listitem>
 163                         </varlistentry>
 164                         <varlistentry>
 165                                 <term><option>--log-target=</option></term>
 166
 167                                 <listitem><para>Set log
 168                                 target. Argument must be one of
 169                                 <option>console</option>,
 170                                 <option>syslog</option>,
 171                                 <option>kmsg</option>,
 172                                 <option>syslog-or-kmsg</option>,
 173                                 <option>null</option>.</para></listitem>
 174                         </varlistentry>
 175                         <varlistentry>
 176                                 <term><option>--log-color=</option></term>
 177
 178                                 <listitem><para>Highlight important
 179                                 log messages. Argument is a boolean
 180                                 value. If the argument is omitted it
 181                                 defaults to
 182                                 <option>true</option>.</para></listitem>
 183                         </varlistentry>
 184                         <varlistentry>
 185                                 <term><option>--log-location=</option></term>
 186
 187                                 <listitem><para>Include code location
 188                                 in log messages. This is mostly
 189                                 relevant for debugging
 190                                 purposes. Argument is a boolean
 191                                 value. If the argument is omitted
 192                                 it defaults to
 193                                 <option>true</option>.</para></listitem>
 194                         </varlistentry>
 195                 </variablelist>
 196         </refsect1>
 197
 198         <refsect1>
 199                 <title>Directories</title>
 200
 201                 <variablelist>
 202                         <varlistentry>
 203                                 <term>System unit directories</term>
 204
 205                                 <listitem><para>The systemd system
 206                                 manager reads unit configuration from
 207                                 various directories. Packages that
 208                                 want to install unit files shall place
 209                                 them in the directory returned by
 210                                 <command>pkg-config systemd
 211                                 --variable=systemdsystemunitdir</command>. Other
 212                                 directories checked are
 213                                 <filename>/usr/local/share/systemd/system</filename>
 214                                 and
 215                                 <filename>/usr/share/systemd/system</filename>. User
 216                                 configuration always takes
 217                                 precedence. <command>pkg-config
 218                                 systemd
 219                                 --variable=systemdsystemconfdir</command>
 220                                 returns the path of the system
 221                                 configuration directory. Packages
 222                                 should alter this directory only with
 223                                 the
 224                                 <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 225                                 tool.</para></listitem>
 226                         </varlistentry>
 227                 </variablelist>
 228
 229                 <variablelist>
 230                         <varlistentry>
 231                                 <term>Session unit directories</term>
 232
 233                                 <listitem><para>Similar rules apply
 234                                 for the session unit
 235                                 directories. However, here the <ulink
 236                                 url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
 237                                 Base Directory specification</ulink>
 238                                 is followed to find
 239                                 units. Applications should place their
 240                                 unit files in the directory returned
 241                                 by <command>pkg-config systemd
 242                                 --variable=systemdsessionunitdir</command>. Global
 243                                 configuration is done in the
 244                                 directory reported by
 245                                 <command>pkg-config systemd
 246                                 --variable=systemdsessionconfdir</command>. The
 247                                 <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 248                                 tool can handle both global (i.e. for
 249                                 all users) and private (for one user)
 250                                 enabling/disabling of
 251                                 units.</para></listitem>
 252                         </varlistentry>
 253                 </variablelist>
 254
 255                 <variablelist>
 256                         <varlistentry>
 257                                 <term>SysV init scripts directory</term>
 258
 259                                 <listitem><para>The location of the
 260                                 SysV init script directory varies
 261                                 between distributions. If systemd
 262                                 cannot find a native unit file for a
 263                                 requested service it will look for a
 264                                 SysV init script of the same name
 265                                 (with the
 266                                 <filename>.service</filename> suffix
 267                                 removed).</para></listitem>
 268                         </varlistentry>
 269                 </variablelist>
 270
 271                 <variablelist>
 272                         <varlistentry>
 273                                 <term>SysV runlevel link farm directory</term>
 274
 275                                 <listitem><para>The location of the
 276                                 SysV runlevel link farm directory
 277                                 varies between distributions. systemd
 278                                 will take the link farm into account
 279                                 when figuring out whether a service
 280                                 shall be enabled. Note that a service
 281                                 unit with a native unit configuration
 282                                 file can be started by activating it
 283                                 in the SysV runlevel link
 284                                 farm.</para></listitem>
 285                         </varlistentry>
 286                 </variablelist>
 287         </refsect1>
 288
 289         <refsect1>
 290                 <title>Signals</title>
 291
 292                 <variablelist>
 293                         <varlistentry>
 294                                 <term>SIGTERM</term>
 295
 296                                 <listitem><para>Upon receiving this
 297                                 signal the systemd system manager
 298                                 serializes its state, reexecutes
 299                                 itself and deserializes the saved
 300                                 state again. This is mostly equivalent
 301                                 to <command>systemctl
 302                                 daemon-reexec</command>.</para>
 303
 304                                 <para>systemd session managers will
 305                                 start the
 306                                 <filename>exit.target</filename> unit
 307                                 when this signal is received. This is
 308                                 mostly equivalent to
 309                                 <command>systemctl --session start
 310                                 exit.target</command>.</para></listitem>
 311                         </varlistentry>
 312
 313                         <varlistentry>
 314                                 <term>SIGINT</term>
 315
 316                                 <listitem><para>Upon receiving this
 317                                 signal the systemd system manager will
 318                                 start the
 319                                 <filename>ctrl-alt-del.target</filename> unit. This
 320                                 is mostly equivalent to
 321                                 <command>systemctl start
 322                                 ctl-alt-del.target</command>.</para>
 323
 324                                 <para>systemd session managers
 325                                 treat this signal the same way as
 326                                 SIGTERM.</para></listitem>
 327                         </varlistentry>
 328
 329                         <varlistentry>
 330                                 <term>SIGWINCH</term>
 331
 332                                 <listitem><para>When this signal is
 333                                 received the systemd system manager
 334                                 will start the
 335                                 <filename>kbrequest.target</filename>
 336                                 unit. This is mostly equivalent to
 337                                 <command>systemctl start
 338                                 kbrequest.target</command>.</para>
 339
 340                                 <para>This signal is ignored by
 341                                 systemd session
 342                                 managers.</para></listitem>
 343                         </varlistentry>
 344
 345                         <varlistentry>
 346                                 <term>SIGPWR</term>
 347
 348                                 <listitem><para>When this signal is
 349                                 received the systemd manager
 350                                 will start the
 351                                 <filename>sigpwr.target</filename>
 352                                 unit. This is mostly equivalent to
 353                                 <command>systemctl start
 354                                 sigpwr.target</command>.</para></listitem>
 355                         </varlistentry>
 356
 357                         <varlistentry>
 358                                 <term>SIGUSR1</term>
 359
 360                                 <listitem><para>When this signal is
 361                                 received the systemd manager will try
 362                                 to reconnect to the D-Bus
 363                                 bus.</para></listitem>
 364                         </varlistentry>
 365
 366                         <varlistentry>
 367                                 <term>SIGUSR2</term>
 368
 369                                 <listitem><para>When this signal is
 370                                 received the systemd manager will log
 371                                 its complete state in human readable
 372                                 form. The data logged is the same as
 373                                 printed by <command>systemctl
 374                                 dump</command>.</para></listitem>
 375                         </varlistentry>
 376
 377                         <varlistentry>
 378                                 <term>SIGHUP</term>
 379
 380                                 <listitem><para>Reloads the complete
 381                                 daemon configuration. This is mostly
 382                                 equivalent to <command>systemctl
 383                                 daemon-reload</command>.</para></listitem>
 384                         </varlistentry>
 385
 386                         <varlistentry>
 387                                 <term>SIGRTMIN+0</term>
 388
 389                                 <listitem><para>Enters default mode, starts the
 390                                 <filename>default.target</filename>
 391                                 unit. This is mostly equivalent to
 392                                 <command>systemctl start
 393                                 default.target</command>.</para></listitem>
 394                         </varlistentry>
 395
 396                         <varlistentry>
 397                                 <term>SIGRTMIN+1</term>
 398
 399                                 <listitem><para>Enters rescue mode,
 400                                 starts the
 401                                 <filename>rescue.target</filename>
 402                                 unit. This is mostly equivalent to
 403                                 <command>systemctl isolate
 404                                 rescue.target</command>.</para></listitem>
 405                         </varlistentry>
 406
 407                         <varlistentry>
 408                                 <term>SIGRTMIN+2</term>
 409
 410                                 <listitem><para>Enters emergency mode,
 411                                 starts the
 412                                 <filename>emergency.service</filename>
 413                                 unit. This is mostly equivalent to
 414                                 <command>systemctl isolate
 415                                 emergency.service</command>.</para></listitem>
 416                         </varlistentry>
 417
 418                         <varlistentry>
 419                                 <term>SIGRTMIN+3</term>
 420
 421                                 <listitem><para>Halts the machine,
 422                                 starts the
 423                                 <filename>halt.target</filename>
 424                                 unit. This is mostly equivalent to
 425                                 <command>systemctl start
 426                                 halt.target</command>.</para></listitem>
 427                         </varlistentry>
 428
 429                         <varlistentry>
 430                                 <term>SIGRTMIN+4</term>
 431
 432                                 <listitem><para>Powers off the machine,
 433                                 starts the
 434                                 <filename>poweroff.target</filename>
 435                                 unit. This is mostly equivalent to
 436                                 <command>systemctl start
 437                                 poweroff.target</command>.</para></listitem>
 438                         </varlistentry>
 439
 440                         <varlistentry>
 441                                 <term>SIGRTMIN+5</term>
 442
 443                                 <listitem><para>Reboots the machine,
 444                                 starts the
 445                                 <filename>reboot.target</filename>
 446                                 unit. This is mostly equivalent to
 447                                 <command>systemctl start
 448                                 reboot.target</command>.</para></listitem>
 449                         </varlistentry>
 450                 </variablelist>
 451         </refsect1>
 452
 453         <refsect1>
 454                 <title>Environment</title>
 455
 456                 <variablelist>
 457                         <varlistentry>
 458                                 <term><varname>$SYSTEMD_LOG_LEVEL</varname></term>
 459                                 <listitem><para>systemd reads the
 460                                 log level from this environment
 461                                 variable. This can be overriden with
 462                                 <option>--log-level=</option>.</para></listitem>
 463                         </varlistentry>
 464
 465                         <varlistentry>
 466                                 <term><varname>$SYSTEMD_LOG_TARGET</varname></term>
 467                                 <listitem><para>systemd reads the
 468                                 log target from this environment
 469                                 variable. This can be overriden with
 470                                 <option>--log-target=</option>.</para></listitem>
 471                         </varlistentry>
 472
 473                         <varlistentry>
 474                                 <term><varname>$SYSTEMD_LOG_COLOR</varname></term>
 475                                 <listitem><para>Controls whether
 476                                 systemd highlights important log
 477                                 messages. This can be overriden with
 478                                 <option>--log-color=</option>.</para></listitem>
 479                         </varlistentry>
 480
 481                         <varlistentry>
 482                                 <term><varname>$SYSTEMD_LOG_LOCATION</varname></term>
 483                                 <listitem><para>Controls whether
 484                                 systemd prints the code location along
 485                                 with log messages. This can be
 486                                 overriden with
 487                                 <option>--log-location=</option>.</para></listitem>
 488                         </varlistentry>
 489
 490                         <varlistentry>
 491                                 <term><varname>$XDG_CONFIG_HOME</varname></term>
 492                                 <term><varname>$XDG_CONFIG_DIRS</varname></term>
 493                                 <term><varname>$XDG_DATA_HOME</varname></term>
 494                                 <term><varname>$XDG_DATA_DIRS</varname></term>
 495
 496                                 <listitem><para>The systemd session
 497                                 manager uses these variables in
 498                                 accordance to the <ulink
 499                                 url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
 500                                 Base Directory specification</ulink>
 501                                 to find its configuration.</para></listitem>
 502                         </varlistentry>
 503
 504                         <varlistentry>
 505                                 <term><varname>$SYSTEMD_UNIT_PATH</varname></term>
 506
 507                                 <listitem><para>Controls where systemd
 508                                 looks for unit
 509                                 files.</para></listitem>
 510                         </varlistentry>
 511
 512                         <varlistentry>
 513                                 <term><varname>$SYSTEMD_SYSVINIT_PATH</varname></term>
 514
 515                                 <listitem><para>Controls where systemd
 516                                 looks for SysV init scripts.</para></listitem>
 517                         </varlistentry>
 518
 519                         <varlistentry>
 520                                 <term><varname>$SYSTEMD_SYSVRCND_PATH</varname></term>
 521
 522                                 <listitem><para>Controls where systemd
 523                                 looks for SysV init script runlevel link
 524                                 farms.</para></listitem>
 525                         </varlistentry>
 526
 527                         <varlistentry>
 528                                 <term><varname>$LISTEN_PID</varname></term>
 529                                 <term><varname>$LISTEN_FDS</varname></term>
 530
 531                                 <listitem><para>Set by systemd for
 532                                 supervised processes during
 533                                 socket-based activation. See
 534                                 <citerefentry><refentrytitle>sd_listen_fds</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 535                                 for more information.
 536                                 </para></listitem>
 537                         </varlistentry>
 538
 539                         <varlistentry>
 540                                 <term><varname>$NOTIFY_SOCKET</varname></term>
 541
 542                                 <listitem><para>Set by systemd for
 543                                 supervised processes for status and
 544                                 start-up completion notification. See
 545                                 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 546                                 for more information.
 547                                 </para></listitem>
 548                         </varlistentry>
 549                 </variablelist>
 550         </refsect1>
 551
 552         <refsect1>
 553                 <title>Sockets and FIFOs</title>
 554
 555                 <variablelist>
 556                         <varlistentry>
 557                                 <term><filename>@/org/freedesktop/systemd1/notify</filename></term>
 558
 559                                 <listitem><para>Daemon status
 560                                 notification socket. This is an AF_UNIX
 561                                 datagram socket in the Linux abstract
 562                                 namespace, and is used to implement
 563                                 the daemon notification logic as
 564                                 implemented by
 565                                 <citerefentry><refentrytitle>sd_notify</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para></listitem>
 566
 567                         </varlistentry>
 568
 569                         <varlistentry>
 570                                 <term><filename>@/org/freedesktop/systemd1/logger</filename></term>
 571
 572                                 <listitem><para>Used internally by the
 573                                 <filename>systemd-logger.service</filename>
 574                                 unit to connect STDOUT and/or STDERR
 575                                 of spawned processes to
 576                                 <citerefentry><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
 577                                 or the kernel log buffer. This is an
 578                                 AF_UNIX stream socket in the Linux
 579                                 abstract namespace.</para></listitem>
 580                         </varlistentry>
 581
 582                         <varlistentry>
 583                                 <term><filename>@/org/freedesktop/systemd1/private</filename></term>
 584
 585                                 <listitem><para>Used internally as
 586                                 communication channel between
 587                                 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 588                                 and the systemd process. This is an
 589                                 AF_UNIX stream socket in the Linux
 590                                 abstract namespace. This interface is
 591                                 private to systemd and should not be
 592                                 used in external
 593                                 projects.</para></listitem>
 594                         </varlistentry>
 595
 596                         <varlistentry>
 597                                 <term><filename>/dev/initctl</filename></term>
 598
 599                                 <listitem><para>Limited compatibility
 600                                 support for the SysV client interface,
 601                                 as implemented by the
 602                                 <filename>systemd-initctl.service</filename>
 603                                 unit. This is a named pipe in the file
 604                                 system. This interface is obsolete and
 605                                 should not be used in new
 606                                 applications.</para></listitem>
 607                         </varlistentry>
 608                 </variablelist>
 609         </refsect1>
 610
 611         <refsect1>
 612                 <title>See Also</title>
 613                 <para>
 614                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 615                         <citerefentry><refentrytitle>systemadm</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 616                         <citerefentry><refentrytitle>systemd-install</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 617                         <citerefentry><refentrytitle>systemd-notify</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 618                         <citerefentry><refentrytitle>daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 619                         <citerefentry><refentrytitle>sd-daemon</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 620                         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 621                         <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 622                         <citerefentry><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 623                 </para>
 624         </refsect1>
 625
 626 </refentry>