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