man/systemctl.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-install">
  25
  26         <refentryinfo>
  27                 <title>systemctl</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>systemctl</refentrytitle>
  42                 <manvolnum>1</manvolnum>
  43         </refmeta>
  44
  45         <refnamediv>
  46                 <refname>systemctl</refname>
  47                 <refpurpose>Control the systemd system and session manager</refpurpose>
  48         </refnamediv>
  49
  50         <refsynopsisdiv>
  51                 <cmdsynopsis>
  52                         <command>systemctl <arg choice="opt" rep="repeat">OPTIONS</arg> <arg choice="req">COMMAND</arg> <arg choice="opt" rep="repeat">NAME</arg></command>
  53                 </cmdsynopsis>
  54         </refsynopsisdiv>
  55
  56         <refsect1>
  57                 <title>Description</title>
  58
  59                 <para><command>systemctl</command> may be used to
  60                 introspect and control the state of the
  61                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  62                 system and session manager.</para>
  63         </refsect1>
  64
  65         <refsect1>
  66                 <title>Options</title>
  67
  68                 <para>The following options are understood:</para>
  69
  70                 <variablelist>
  71                         <varlistentry>
  72                                 <term><option>--help</option></term>
  73                                 <term><option>-h</option></term>
  74
  75                                 <listitem><para>Prints a short help
  76                                 text and exits.</para></listitem>
  77                         </varlistentry>
  78
  79                         <varlistentry>
  80                                 <term><option>--type=</option></term>
  81                                 <term><option>-t</option></term>
  82
  83                                 <listitem><para>When listing units,
  84                                 limit display to certain unit
  85                                 types. If not specified units of all
  86                                 types will be shown. The argument
  87                                 should be a unit type name such as
  88                                 <option>service</option>,
  89                                 <option>socket</option> and
  90                                 similar.</para></listitem>
  91                         </varlistentry>
  92
  93                         <varlistentry>
  94                                 <term><option>--property=</option></term>
  95                                 <term><option>-p</option></term>
  96
  97                                 <listitem><para>When showing
  98                                 unit/job/manager information, limit
  99                                 display to certain property names. If
 100                                 not specified all set properties are
 101                                 shown. The argument should be a
 102                                 property name, such as
 103                                 <literal>MainPID</literal>.</para></listitem>
 104                         </varlistentry>
 105
 106                         <varlistentry>
 107                                 <term><option>--all</option></term>
 108                                 <term><option>-a</option></term>
 109
 110                                 <listitem><para>When listing units,
 111                                 show all units, regardless of their
 112                                 state, including inactive units. When
 113                                 showing unit/job/manager information,
 114                                 show all properties regardless whether
 115                                 they are set or not.</para></listitem>
 116                         </varlistentry>
 117
 118                         <varlistentry>
 119                                 <term><option>--full</option></term>
 120
 121                                 <listitem><para>Do not ellipsize unit
 122                                 names in the output of
 123                                 <command>list-units</command> and
 124                                 <command>list-jobs</command>.</para></listitem>
 125                         </varlistentry>
 126
 127                         <varlistentry>
 128                                 <term><option>--fail</option></term>
 129
 130                                 <listitem><para>If the requested
 131                                 operation conflicts with an existing
 132                                 unfinished operation, fail the
 133                                 command. If this is not specified the
 134                                 requested operation will replace the
 135                                 pending job if
 136                                 necessary.</para></listitem>
 137                         </varlistentry>
 138
 139                         <varlistentry>
 140                                 <term><option>--order</option></term>
 141                                 <term><option>--require</option></term>
 142
 143                                 <listitem><para>When used in
 144                                 conjunction with the
 145                                 <command>dot</command> command (see
 146                                 below), selects which dependencies are
 147                                 shown in the dependency graph. If
 148                                 <option>--order</option> is passed
 149                                 only dependencies of type
 150                                 <varname>After=</varname> or
 151                                 <varname>Before=</varname> are
 152                                 shown. If <option>--require</option>
 153                                 is passed only dependencies of type
 154                                 <varname>Requires=</varname>,
 155                                 <varname>RequiresOverridable=</varname>,
 156                                 <varname>Requisite=</varname>,
 157                                 <varname>RequisiteOverridable=</varname>,
 158                                 <varname>Wants=</varname> and
 159                                 <varname>Conflicts=</varname> are
 160                                 shown. If neither is passed, shows
 161                                 dependencies of all these
 162                                 types.</para></listitem>
 163                         </varlistentry>
 164
 165                         <varlistentry>
 166                                 <term><option>--system</option></term>
 167
 168                                 <listitem><para>Talk to the systemd
 169                                 system manager. (Default)</para></listitem>
 170                         </varlistentry>
 171
 172                         <varlistentry>
 173                                 <term><option>--session</option></term>
 174
 175                                 <listitem><para>Talk to the systemd
 176                                 session manager of the calling user.</para></listitem>
 177                         </varlistentry>
 178
 179                         <varlistentry>
 180                                 <term><option>--no-block</option></term>
 181
 182                                 <listitem><para>Do not synchronously wait for
 183                                 the requested operation to finish. If this is
 184                                 not specified the job will be verified,
 185                                 enqueued and <command>systemctl</command> will
 186                                 wait until it is completed. By passing this
 187                                 argument it is only verified and
 188                                 enqueued.</para></listitem> </varlistentry>
 189
 190                         <varlistentry>
 191                                 <term><option>--quiet</option></term>
 192                                 <term><option>-q</option></term>
 193
 194                                 <listitem><para>Suppress output to
 195                                 STDOUT for <command>snapshot</command>
 196                                 and
 197                                 <command>check</command>.</para></listitem>
 198                         </varlistentry>
 199
 200                         <varlistentry>
 201                                 <term><option>--no-wall</option></term>
 202
 203                                 <listitem><para>Don't send wall
 204                                 message before
 205                                 halt, power-off, reboot.</para></listitem>
 206                         </varlistentry>
 207                 </variablelist>
 208
 209                 <para>The following commands are understood:</para>
 210
 211                 <variablelist>
 212                         <varlistentry>
 213                                 <term><command>list-units</command></term>
 214
 215                                 <listitem><para>List known units.</para></listitem>
 216                         </varlistentry>
 217                         <varlistentry>
 218                                 <term><command>start [NAME...]</command></term>
 219
 220                                 <listitem><para>Start one or more
 221                                 units specified on the command
 222                                 line.</para></listitem>
 223                         </varlistentry>
 224                         <varlistentry>
 225                                 <term><command>stop [NAME...]</command></term>
 226
 227                                 <listitem><para>Stop one or more units
 228                                 specified on the command
 229                                 line.</para></listitem>
 230                         </varlistentry>
 231                         <varlistentry>
 232                                 <term><command>reload [NAME...]</command></term>
 233
 234                                 <listitem><para>Asks all services
 235                                 whose units are listed on the command
 236                                 line to reload their
 237                                 configuration. Note that this will
 238                                 reload the daemon configuration
 239                                 itself, not the unit configuration
 240                                 file of systemd. If you want systemd
 241                                 to reload the configuration file of a
 242                                 unit use the
 243                                 <command>daemon-reload</command>
 244                                 command. In other words: for the
 245                                 example case of Apache, this will
 246                                 reload Apache's
 247                                 <filename>httpd.conf</filename> in the
 248                                 web server, not the
 249                                 <filename>apache.service</filename>
 250                                 systemd unit file. </para> <para>This
 251                                 command should not be confused with
 252                                 the <command>daemon-reload</command>
 253                                 or <command>load</command>
 254                                 commands.</para></listitem>
 255
 256                         </varlistentry>
 257                         <varlistentry>
 258                                 <term><command>restart [NAME...]</command></term>
 259
 260                                 <listitem><para>Restart one or more
 261                                 units specified on the command
 262                                 line. If the units are not running yet
 263                                 they will be
 264                                 started.</para></listitem>
 265                         </varlistentry>
 266                         <varlistentry>
 267                                 <term><command>try-restart [NAME...]</command></term>
 268
 269                                 <listitem><para>Restart one or more
 270                                 units specified on the command
 271                                 line. If the units are not running yet
 272                                 the operation will
 273                                 fail.</para></listitem>
 274                         </varlistentry>
 275                         <varlistentry>
 276                                 <term><command>reload-or-restart [NAME...]</command></term>
 277                                 <term><command>reload-or-try-restart [NAME...]</command></term>
 278
 279                                 <listitem><para>Reload one or more
 280                                 units if they support it. If not
 281                                 restart them
 282                                 instead.</para></listitem>
 283                         </varlistentry>
 284                         <varlistentry>
 285                                 <term><command>isolate [NAME]</command></term>
 286
 287                                 <listitem><para>Start the unit
 288                                 specified on the command line and its
 289                                 dependencies and stop all
 290                                 others.</para></listitem>
 291                         </varlistentry>
 292                         <varlistentry>
 293                                 <term><command>check [NAME...]</command></term>
 294
 295                                 <listitem><para>Check whether any of
 296                                 the specified units is active
 297                                 (i.e. running). Returns 0 if at least
 298                                 one is active, non-zero
 299                                 otherwise. Unless
 300                                 <option>--quiet</option> is specified
 301                                 this will also print the current unit
 302                                 state to STDOUT.</para></listitem>
 303                         </varlistentry>
 304                         <varlistentry>
 305                                 <term><command>status [NAME...]</command></term>
 306
 307                                 <listitem><para>Show short status
 308                                 information about one or more
 309                                 units. This shows terse runtime
 310                                 information about
 311                                 units.</para></listitem>
 312                         </varlistentry>
 313                         <varlistentry>
 314                                 <term><command>show [NAME...|JOB...]</command></term>
 315
 316                                 <listitem><para>Show properties of
 317                                 one or more units, jobs or the manager
 318                                 itself. If no argument is specified
 319                                 properties of the manager will be
 320                                 shown. If a unit name is specified
 321                                 properties of the unit is shown,
 322                                 and if a job id is specified
 323                                 properties of the job is
 324                                 shown.</para></listitem>
 325                         </varlistentry>
 326
 327                         <varlistentry>
 328                                 <term><command>reset-maintenance [NAME...]</command></term>
 329
 330                                 <listitem><para>Reset maintenance
 331                                 state of the specified units, or if no
 332                                 unit name is passed of all units. When
 333                                 a unit fails in some way (i.e. process
 334                                 exiting with non-zero error code,
 335                                 terminating abnormally or timing out)
 336                                 it will automatically enter
 337                                 maintenance state and its exit codes
 338                                 and status is recorded for
 339                                 introspection by the administrator
 340                                 until the service is restarted or
 341                                 reset with this
 342                                 command.</para></listitem>
 343                         </varlistentry>
 344
 345                         <varlistentry>
 346                                 <term><command>load [NAME...]</command></term>
 347
 348                                 <listitem><para>Load one or more units
 349                                 specified on the command line. This
 350                                 will simply load their configuration
 351                                 from disk, but not start them. To
 352                                 start them you need to use the
 353                                 <command>start</command> command which
 354                                 will implicitly load a unit that has
 355                                 not been loaded yet. Note that systemd
 356                                 garbage collects loaded units that are
 357                                 not active or referenced by an active
 358                                 unit. This means that units loaded
 359                                 this way will usually not stay loaded
 360                                 for long. Also note that this command
 361                                 cannot be used to reload unit
 362                                 configuration. Use the
 363                                 <command>daemon-reload</command>
 364                                 command for that. All in all, this
 365                                 command is of little use except for
 366                                 debugging.</para>
 367                                 <para>This command should not be
 368                                 confused with the
 369                                 <command>daemon-reload</command> or
 370                                 <command>reload</command>
 371                                 commands.</para></listitem>
 372                         </varlistentry>
 373                         <varlistentry>
 374                                 <term><command>list-jobs</command></term>
 375
 376                                 <listitem><para>List jobs that are in progress.</para></listitem>
 377                         </varlistentry>
 378                         <varlistentry>
 379                                 <term><command>cancel [JOB...]</command></term>
 380
 381                                 <listitem><para>Cancel one or more
 382                                 jobs specified on the command line by
 383                                 their numeric job
 384                                 IDs.</para></listitem>
 385                         </varlistentry>
 386                         <varlistentry>
 387                                 <term><command>clear-jobs</command></term>
 388
 389                                 <listitem><para>Cancel all jobs that are in progress.</para></listitem>
 390                         </varlistentry>
 391                         <varlistentry>
 392                                 <term><command>monitor</command></term>
 393
 394                                 <listitem><para>Monitor unit/job
 395                                 changes. This is mostly useful for
 396                                 debugging purposes and prints a line
 397                                 each time systemd loads or unloads a
 398                                 unit configuration file, or a unit
 399                                 property changes.</para></listitem>
 400                         </varlistentry>
 401                         <varlistentry>
 402                                 <term><command>dump</command></term>
 403
 404                                 <listitem><para>Dump server
 405                                 status. This will output a (usually
 406                                 very long) human readable manager
 407                                 status dump. Its format is subject to
 408                                 change without notice and should not
 409                                 be parsed by
 410                                 applications.</para></listitem>
 411                         </varlistentry>
 412                         <varlistentry>
 413                                 <term><command>dot</command></term>
 414
 415                                 <listitem><para>Generate textual
 416                                 dependency graph description in dot
 417                                 format for further processing with the
 418                                 GraphViz
 419                                 <citerefentry><refentrytitle>dot</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 420                                 tool. Use a command line like
 421                                 <command>systemctl dot | dot -Tsvg >
 422                                 systemd.svg</command> to generate a
 423                                 graphical dependency tree. Unless
 424                                 <option>--order</option> or
 425                                 <option>--require</option> is passed
 426                                 the generated graph will show both
 427                                 ordering and requirement
 428                                 dependencies.</para></listitem>
 429                         </varlistentry>
 430                         <varlistentry>
 431                                 <term><command>snapshot [NAME]</command></term>
 432
 433                                 <listitem><para>Create a snapshot. If
 434                                 a snapshot name is specified, the new
 435                                 snapshot will be named after it. If
 436                                 none is specified an automatic
 437                                 snapshot name is generated. In either
 438                                 case, the snapshot name used is
 439                                 printed to STDOUT, unless
 440                                 <option>--quiet</option> is
 441                                 specified.</para>
 442
 443                                 <para>A snapshot refers to a saved
 444                                 state of the systemd manager. It is
 445                                 implemented itself as unit that is
 446                                 generated dynamically with this
 447                                 command and has dependencies on all
 448                                 units active at the time. At a later
 449                                 time the user may return to this state
 450                                 by using the
 451                                 <command>isolate</command> command on
 452                                 the snapshot unit.</para></listitem>
 453
 454                                 <para>Snapshots are only useful for
 455                                 saving and restoring which units are
 456                                 running or are stopped, they do not
 457                                 save/restore any other
 458                                 state. Snapshots are dynamic and lost
 459                                 on reboot.</para>
 460                         </varlistentry>
 461                         <varlistentry>
 462                                 <term><command>delete [NAME...]</command></term>
 463
 464                                 <listitem><para>Remove a snapshot
 465                                 previously created with
 466                                 <command>snapshot</command>.</para></listitem>
 467                         </varlistentry>
 468                         <varlistentry>
 469                                 <term><command>daemon-reload</command></term>
 470
 471                                 <listitem><para>Reload systemd manager
 472                                 configuration. This will reload all
 473                                 unit files and recreate the entire
 474                                 dependency tree. While the daemon is
 475                                 reloaded, all sockets systemd listens
 476                                 on on behalf of user configuration will
 477                                 stay accessible.</para> <para>This
 478                                 command should not be confused with
 479                                 the <command>load</command> or
 480                                 <command>reload</command>
 481                                 commands.</para></listitem>
 482                         </varlistentry>
 483                         <varlistentry>
 484                                 <term><command>daemon-reexec</command></term>
 485
 486                                 <listitem><para>Reexecute the systemd
 487                                 manager. This will serialize the
 488                                 manager state, reexecute the process
 489                                 and deserialize the state again. This
 490                                 command is of little use except for
 491                                 debugging and package
 492                                 upgrades. Sometimes it might be
 493                                 helpful as a heavy-weight
 494                                 <command>daemon-reload</command>. While
 495                                 the daemon is reexecuted all sockets
 496                                 systemd listens on on behalf of user
 497                                 configuration will stay
 498                                 accessible.</para></listitem>
 499                         </varlistentry>
 500                         <varlistentry>
 501                                 <term><command>daemon-exit</command></term>
 502
 503                                 <listitem><para>Ask the systemd
 504                                 manager to quit. This is only
 505                                 supported for session managers
 506                                 (i.e. in conjunction with the
 507                                 <option>--session</option> option) and
 508                                 will fail otherwise.</para></listitem>
 509                         </varlistentry>
 510                         <varlistentry>
 511                                 <term><command>show-environment</command></term>
 512
 513                                 <listitem><para>Dump the systemd
 514                                 manager environment block. The
 515                                 environment block will be dumped in
 516                                 straight-forward form suitable for
 517                                 sourcing into a shell script. This
 518                                 environment block will be passed to
 519                                 all processes the manager
 520                                 spawns.</para></listitem>
 521                         </varlistentry>
 522                         <varlistentry>
 523                                 <term><command>set-environment [NAME=VALUE...]</command></term>
 524
 525                                 <listitem><para>Set one or more
 526                                 systemd manager environment variables,
 527                                 as specified on the command
 528                                 line.</para></listitem>
 529                         </varlistentry>
 530                         <varlistentry>
 531                                 <term><command>unset-environment [NAME...]</command></term>
 532
 533                                 <listitem><para>Unset one or more
 534                                 systemd manager environment
 535                                 variables. If only a variable name is
 536                                 specified it will be removed
 537                                 regardless of its value. If a variable
 538                                 and a value are specified the variable
 539                                 is only removed if it has the
 540                                 specified value.</para></listitem>
 541                         </varlistentry>
 542
 543                         <varlistentry>
 544                                 <term><command>halt</command></term>
 545
 546                                 <listitem><para>Shut down and halt the
 547                                 system. This is mostly equivalent to
 548                                 <command>start halt.target</command>
 549                                 but also prints a wall message to all
 550                                 users.</para></listitem>
 551                         </varlistentry>
 552                         <varlistentry>
 553                                 <term><command>poweroff</command></term>
 554
 555                                 <listitem><para>Shut down and
 556                                 power-off the system. This is mostly
 557                                 equivalent to <command>start
 558                                 poweroff.target</command> but also
 559                                 prints a wall message to all
 560                                 users.</para></listitem>
 561                         </varlistentry>
 562                         <varlistentry>
 563                                 <term><command>reboot</command></term>
 564
 565                                 <listitem><para>Shut down and
 566                                 reboot the system. This is mostly
 567                                 equivalent to <command>start
 568                                 reboot.target</command> but also
 569                                 prints a wall message to all
 570                                 users.</para></listitem>
 571                         </varlistentry>
 572                         <varlistentry>
 573                                 <term><command>default</command></term>
 574
 575                                 <listitem><para>Enter default
 576                                 mode. This is mostly equivalent to
 577                                 <command>start
 578                                 default.target</command>.</para></listitem>
 579                         </varlistentry>
 580                         <varlistentry>
 581                                 <term><command>rescue</command></term>
 582
 583                                 <listitem><para>Enter rescue
 584                                 mode. This is mostly equivalent to
 585                                 <command>isolate
 586                                 rescue.target</command> but also
 587                                 prints a wall message to all
 588                                 users.</para></listitem>
 589                         </varlistentry>
 590                         <varlistentry>
 591                                 <term><command>emergency</command></term>
 592
 593                                 <listitem><para>Enter emergency
 594                                 mode. This is mostly equivalent to
 595                                 <command>isolate
 596                                 emergency.target</command> but also
 597                                 prints a wall message to all
 598                                 users.</para></listitem>
 599                         </varlistentry>
 600                 </variablelist>
 601
 602         </refsect1>
 603
 604         <refsect1>
 605                 <title>Exit status</title>
 606
 607                 <para>On success 0 is returned, a non-zero failure
 608                 code otherwise.</para>
 609         </refsect1>
 610
 611         <refsect1>
 612                 <title>See Also</title>
 613                 <para>
 614                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 615                         <citerefentry><refentrytitle>systemadm</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 616                         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 617                         <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 618                         <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 619                 </para>
 620         </refsect1>
 621
 622 </refentry>