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