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