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