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