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