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