man/systemctl.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2010 Lennart Poettering
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="systemctl"
  28           xmlns:xi="http://www.w3.org/2001/XInclude">
  29
  30   <refentryinfo>
  31     <title>systemctl</title>
  32     <productname>systemd</productname>
  33
  34     <authorgroup>
  35       <author>
  36         <contrib>Developer</contrib>
  37         <firstname>Lennart</firstname>
  38         <surname>Poettering</surname>
  39         <email>lennart@poettering.net</email>
  40       </author>
  41     </authorgroup>
  42   </refentryinfo>
  43
  44   <refmeta>
  45     <refentrytitle>systemctl</refentrytitle>
  46     <manvolnum>1</manvolnum>
  47   </refmeta>
  48
  49   <refnamediv>
  50     <refname>systemctl</refname>
  51     <refpurpose>Control the systemd system and service manager</refpurpose>
  52   </refnamediv>
  53
  54   <refsynopsisdiv>
  55     <cmdsynopsis>
  56       <command>systemctl</command>
  57       <arg choice="opt" rep="repeat">OPTIONS</arg>
  58       <arg choice="plain">COMMAND</arg>
  59       <arg choice="opt" rep="repeat">NAME</arg>
  60     </cmdsynopsis>
  61   </refsynopsisdiv>
  62
  63   <refsect1>
  64     <title>Description</title>
  65
  66     <para><command>systemctl</command> may be used to introspect and
  67     control the state of the <literal>systemd</literal> system and
  68     service manager. Please refer to
  69     <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  70     for an introduction into the basic concepts and functionality this
  71     tool manages.</para>
  72   </refsect1>
  73
  74   <refsect1>
  75     <title>Options</title>
  76
  77     <para>The following options are understood:</para>
  78
  79     <variablelist>
  80       <varlistentry>
  81         <term><option>-t</option></term>
  82         <term><option>--type=</option></term>
  83
  84         <listitem>
  85           <para>The argument should be a comma-separated list of unit
  86           types such as <option>service</option> and
  87           <option>socket</option>.
  88           </para>
  89
  90           <para>If one of the arguments is a unit type, when listing
  91           units, limit display to certain unit types. Otherwise, units
  92           of all types will be shown.</para>
  93
  94           <para>As a special case, if one of the arguments is
  95           <option>help</option>, a list of allowed values will be
  96           printed and the program will exit.</para>
  97         </listitem>
  98       </varlistentry>
  99
 100       <varlistentry>
 101         <term><option>--state=</option></term>
 102
 103         <listitem>
 104         <para>The argument should be a comma-separated list of unit
 105         LOAD, SUB, or ACTIVE states. When listing units, show only
 106         those in specified states. Use <option>--state=failed</option>
 107         to show only failed units.</para>
 108         </listitem>
 109       </varlistentry>
 110
 111       <varlistentry>
 112         <term><option>-p</option></term>
 113         <term><option>--property=</option></term>
 114
 115         <listitem>
 116           <para>When showing unit/job/manager properties with the
 117           <command>show</command> command, limit display to properties
 118           specified in the argument. The argument should be a
 119           comma-separated list of property names, such as
 120           <literal>MainPID</literal>. Unless specified, all known
 121           properties are shown. If specified more than once, all
 122           properties with the specified names are shown. Shell
 123           completion is implemented for property names.</para>
 124
 125           <para>For the manager itself,
 126           <command>systemctl show</command> will show all available
 127           properties. Those properties are documented in
 128           <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 129           </para>
 130
 131           <para>Properties for units vary by unit type, so showing any
 132           unit (even a non-existent one) is a way to list properties
 133           pertaining to this type. Similarly showing any job will list
 134           properties pertaining to all jobs. Properties for units are
 135           documented in
 136           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 137           and the pages for individual unit types
 138           <citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 139           <citerefentry><refentrytitle>systemd.socket</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 140           etc.</para>
 141         </listitem>
 142       </varlistentry>
 143
 144       <varlistentry>
 145         <term><option>-a</option></term>
 146         <term><option>--all</option></term>
 147
 148         <listitem>
 149           <para>When listing units, show all loaded units, regardless
 150           of their state, including inactive units. When showing
 151           unit/job/manager properties, show all properties regardless
 152           whether they are set or not.</para>
 153           <para>To list all units installed on the system, use the
 154           <command>list-unit-files</command> command instead.</para>
 155         </listitem>
 156       </varlistentry>
 157
 158       <varlistentry>
 159         <term><option>-r</option></term>
 160         <term><option>--recursive</option></term>
 161
 162         <listitem>
 163           <para>When listing units, also show units of local
 164           containers. Units of local containers will be prefixed with
 165           the container name, separated by a single colon character
 166           (<literal>:</literal>).</para>
 167         </listitem>
 168       </varlistentry>
 169
 170       <varlistentry>
 171         <term><option>--reverse</option></term>
 172
 173         <listitem>
 174           <para>Show reverse dependencies between units with
 175           <command>list-dependencies</command>, i.e. follow
 176           dependencies of type <varname>WantedBy=</varname>,
 177           <varname>RequiredBy=</varname>,
 178           <varname>RequiredByOverridable=</varname>,
 179           <varname>PartOf=</varname>, <varname>BoundBy=</varname>,
 180           instead of <varname>Wants=</varname> and similar.
 181           </para>
 182         </listitem>
 183       </varlistentry>
 184
 185       <varlistentry>
 186         <term><option>--after</option></term>
 187
 188         <listitem>
 189           <para>With <command>list-dependencies</command>, show the
 190           units that are ordered before the specified unit. In other
 191           words, recursively list units following the
 192           <varname>After=</varname> dependency.</para>
 193
 194           <para>Note that any <varname>After=</varname> dependency is
 195           automatically mirrored to create a
 196           <varname>Before=</varname> dependency. Temporal dependencies
 197           may be specified explicitly, but are also created implicitly
 198           for units which are <varname>WantedBy=</varname> targets
 199           (see
 200           <citerefentry><refentrytitle>systemd.target</refentrytitle><manvolnum>5</manvolnum></citerefentry>),
 201           and as a result of other directives (for example
 202           <varname>RequiresMountsFor=</varname>). Both explicitly
 203           and implicitly introduced dependencies are shown with
 204           <command>list-dependencies</command>.</para>
 205         </listitem>
 206       </varlistentry>
 207
 208       <varlistentry>
 209         <term><option>--before</option></term>
 210
 211         <listitem>
 212           <para>With <command>list-dependencies</command>, show the
 213           units that are ordered after the specified unit. In other
 214           words, recursively list units following the
 215           <varname>Before=</varname> dependency.</para>
 216         </listitem>
 217       </varlistentry>
 218
 219       <varlistentry>
 220         <term><option>-l</option></term>
 221         <term><option>--full</option></term>
 222
 223         <listitem>
 224           <para>Do not ellipsize unit names, process tree entries,
 225           journal output, or truncate unit descriptions in the output
 226           of <command>status</command>, <command>list-units</command>,
 227           <command>list-jobs</command>, and
 228           <command>list-timers</command>.</para>
 229         </listitem>
 230       </varlistentry>
 231
 232       <varlistentry>
 233         <term><option>--show-types</option></term>
 234
 235         <listitem>
 236           <para>When showing sockets, show the type of the socket.</para>
 237         </listitem>
 238       </varlistentry>
 239
 240       <varlistentry>
 241         <term><option>--job-mode=</option></term>
 242
 243         <listitem>
 244         <para>When queuing a new job, this option controls how to deal with
 245         already queued jobs. It takes one of <literal>fail</literal>,
 246         <literal>replace</literal>,
 247         <literal>replace-irreversibly</literal>,
 248         <literal>isolate</literal>,
 249         <literal>ignore-dependencies</literal>,
 250         <literal>ignore-requirements</literal> or
 251         <literal>flush</literal>. Defaults to
 252         <literal>replace</literal>, except when the
 253         <command>isolate</command> command is used which implies the
 254         <literal>isolate</literal> job mode.</para>
 255
 256         <para>If <literal>fail</literal> is specified and a requested
 257         operation conflicts with a pending job (more specifically:
 258         causes an already pending start job to be reversed into a stop
 259         job or vice versa), cause the operation to fail.</para>
 260
 261         <para>If <literal>replace</literal> (the default) is
 262         specified, any conflicting pending job will be replaced, as
 263         necessary.</para>
 264
 265         <para>If <literal>replace-irreversibly</literal> is specified,
 266         operate like <literal>replace</literal>, but also mark the new
 267         jobs as irreversible. This prevents future conflicting
 268         transactions from replacing these jobs (or even being enqueued
 269         while the irreversible jobs are still pending). Irreversible
 270         jobs can still be cancelled using the <command>cancel</command>
 271         command.</para>
 272
 273         <para><literal>isolate</literal> is only valid for start
 274         operations and causes all other units to be stopped when the
 275         specified unit is started. This mode is always used when the
 276         <command>isolate</command> command is used.</para>
 277
 278         <para><literal>flush</literal> will cause all queued jobs to
 279         be canceled when the new job is enqueued.</para>
 280
 281         <para>If <literal>ignore-dependencies</literal> is specified,
 282         then all unit dependencies are ignored for this new job and
 283         the operation is executed immediately. If passed, no required
 284         units of the unit passed will be pulled in, and no ordering
 285         dependencies will be honored. This is mostly a debugging and
 286         rescue tool for the administrator and should not be used by
 287         applications.</para>
 288
 289         <para><literal>ignore-requirements</literal> is similar to
 290         <literal>ignore-dependencies</literal>, but only causes the
 291         requirement dependencies to be ignored, the ordering
 292         dependencies will still be honoured.</para>
 293         </listitem>
 294
 295       </varlistentry>
 296
 297       <varlistentry>
 298         <term><option>--fail</option></term>
 299
 300         <listitem>
 301           <para>Shorthand for <option>--job-mode=</option>fail.</para>
 302           <para>When used with the <command>kill</command> command,
 303           if no units were killed, the operation results in an error.
 304           </para>
 305         </listitem>
 306       </varlistentry>
 307
 308       <varlistentry>
 309         <term><option>-i</option></term>
 310         <term><option>--ignore-inhibitors</option></term>
 311
 312         <listitem>
 313           <para>When system shutdown or a sleep state is requested,
 314           ignore inhibitor locks. Applications can establish inhibitor
 315           locks to avoid that certain important operations (such as CD
 316           burning or suchlike) are interrupted by system shutdown or a
 317           sleep state. Any user may take these locks and privileged
 318           users may override these locks. If any locks are taken,
 319           shutdown and sleep state requests will normally fail
 320           (regardless of whether privileged or not) and a list of active locks
 321           is printed. However, if <option>--ignore-inhibitors</option>
 322           is specified, the locks are ignored and not printed, and the
 323           operation attempted anyway, possibly requiring additional
 324           privileges.</para>
 325         </listitem>
 326       </varlistentry>
 327
 328       <varlistentry>
 329         <term><option>-q</option></term>
 330         <term><option>--quiet</option></term>
 331
 332         <listitem>
 333           <para>Suppress printing of the results of various commands
 334           and also the hints about truncated log lines. This does not
 335           suppress output of commands for which the printed output is
 336           the only result (like <command>show</command>). Errors are
 337           always printed.</para>
 338         </listitem>
 339       </varlistentry>
 340
 341       <varlistentry>
 342         <term><option>--no-block</option></term>
 343
 344         <listitem>
 345           <para>Do not synchronously wait for the requested operation
 346           to finish. If this is not specified, the job will be
 347           verified, enqueued and <command>systemctl</command> will
 348           wait until the unit's start-up is completed. By passing this
 349           argument, it is only verified and enqueued.</para>
 350         </listitem>
 351       </varlistentry>
 352
 353       <xi:include href="user-system-options.xml" xpointer="user" />
 354       <xi:include href="user-system-options.xml" xpointer="system" />
 355
 356       <!-- we do not document -failed here, as it has been made
 357            redundant by -state=failed, which it predates. To keep
 358            things simple we only document the new switch, while
 359            keeping the old one around for compatibility only. -->
 360
 361       <varlistentry>
 362         <term><option>--no-wall</option></term>
 363
 364         <listitem>
 365           <para>Do not send wall message before halt, power-off,
 366           reboot.</para>
 367         </listitem>
 368       </varlistentry>
 369
 370       <varlistentry>
 371         <term><option>--global</option></term>
 372
 373         <listitem>
 374           <para>When used with <command>enable</command> and
 375           <command>disable</command>, operate on the global user
 376           configuration directory, thus enabling or disabling a unit
 377           file globally for all future logins of all users.</para>
 378         </listitem>
 379       </varlistentry>
 380
 381       <varlistentry>
 382         <term><option>--no-reload</option></term>
 383
 384         <listitem>
 385           <para>When used with <command>enable</command> and
 386           <command>disable</command>, do not implicitly reload daemon
 387           configuration after executing the changes.</para>
 388         </listitem>
 389       </varlistentry>
 390
 391       <varlistentry>
 392         <term><option>--no-ask-password</option></term>
 393
 394         <listitem>
 395           <para>When used with <command>start</command> and related
 396           commands, disables asking for passwords. Background services
 397           may require input of a password or passphrase string, for
 398           example to unlock system hard disks or cryptographic
 399           certificates. Unless this option is specified and the
 400           command is invoked from a terminal,
 401           <command>systemctl</command> will query the user on the
 402           terminal for the necessary secrets. Use this option to
 403           switch this behavior off. In this case, the password must be
 404           supplied by some other means (for example graphical password
 405           agents) or the service might fail. This also disables
 406           querying the user for authentication for privileged
 407           operations.</para>
 408         </listitem>
 409       </varlistentry>
 410
 411       <varlistentry>
 412         <term><option>--kill-who=</option></term>
 413
 414         <listitem>
 415           <para>When used with <command>kill</command>, choose which
 416           processes to send a signal to. Must be one of
 417           <option>main</option>, <option>control</option> or
 418           <option>all</option> to select whether to kill only the main
 419           process, the control process or all processes of the
 420           unit. The main process of the unit is the one that defines
 421           the life-time of it. A control process of a unit is one that
 422           is invoked by the manager to induce state changes of it. For
 423           example, all processes started due to the
 424           <varname>ExecStartPre=</varname>,
 425           <varname>ExecStop=</varname> or
 426           <varname>ExecReload=</varname> settings of service units are
 427           control processes. Note that there is only one control
 428           process per unit at a time, as only one state change is
 429           executed at a time. For services of type
 430           <varname>Type=forking</varname>, the initial process started
 431           by the manager for <varname>ExecStart=</varname> is a
 432           control process, while the process ultimately forked off by
 433           that one is then considered the main process of the unit (if
 434           it can be determined). This is different for service units
 435           of other types, where the process forked off by the manager
 436           for <varname>ExecStart=</varname> is always the main process
 437           itself. A service unit consists of zero or one main process,
 438           zero or one control process plus any number of additional
 439           processes. Not all unit types manage processes of these
 440           types however. For example, for mount units, control processes
 441           are defined (which are the invocations of
 442           <filename>&MOUNT_PATH;</filename> and
 443           <filename>&UMOUNT_PATH;</filename>), but no main process
 444           is defined. If omitted, defaults to
 445           <option>all</option>.</para>
 446         </listitem>
 447
 448       </varlistentry>
 449
 450       <varlistentry>
 451         <term><option>-s</option></term>
 452         <term><option>--signal=</option></term>
 453
 454         <listitem>
 455           <para>When used with <command>kill</command>, choose which
 456           signal to send to selected processes. Must be one of the
 457           well known signal specifiers such as <constant>SIGTERM</constant>, <constant>SIGINT</constant> or
 458           <constant>SIGSTOP</constant>. If omitted, defaults to
 459           <option>SIGTERM</option>.</para>
 460         </listitem>
 461       </varlistentry>
 462
 463       <varlistentry>
 464         <term><option>-f</option></term>
 465         <term><option>--force</option></term>
 466
 467         <listitem>
 468           <para>When used with <command>enable</command>, overwrite
 469           any existing conflicting symlinks.</para>
 470
 471           <para>When used with <command>halt</command>,
 472           <command>poweroff</command>, <command>reboot</command> or
 473           <command>kexec</command>, execute the selected operation
 474           without shutting down all units. However, all processes will
 475           be killed forcibly and all file systems are unmounted or
 476           remounted read-only. This is hence a drastic but relatively
 477           safe option to request an immediate reboot. If
 478           <option>--force</option> is specified twice for these
 479           operations, they will be executed immediately without
 480           terminating any processes or unmounting any file
 481           systems. Warning: specifying <option>--force</option> twice
 482           with any of these operations might result in data
 483           loss.</para>
 484         </listitem>
 485       </varlistentry>
 486
 487       <varlistentry>
 488         <term><option>--message=</option></term>
 489
 490         <listitem>
 491           <para>When used with <command>halt</command>,
 492           <command>poweroff</command>, <command>reboot</command> or
 493           <command>kexec</command>, set a short message explaining the reason
 494           for the operation. The message will be logged together with the
 495           default shutdown message.</para>
 496         </listitem>
 497       </varlistentry>
 498
 499       <varlistentry>
 500         <term><option>--now</option></term>
 501
 502         <listitem>
 503           <para>When used with <command>enable</command>, the units
 504           will also be started. When used with <command>disable</command> or
 505           <command>mask</command>, the units will also be stopped. The start
 506           or stop operation is only carried out when the respective enable or
 507           disable operation has been successful.</para>
 508         </listitem>
 509       </varlistentry>
 510
 511       <varlistentry>
 512         <term><option>--root=</option></term>
 513
 514         <listitem>
 515           <para>When used with
 516           <command>enable</command>/<command>disable</command>/<command>is-enabled</command>
 517           (and related commands), use alternative root path when
 518           looking for unit files.</para>
 519         </listitem>
 520
 521       </varlistentry>
 522
 523       <varlistentry>
 524         <term><option>--runtime</option></term>
 525
 526         <listitem>
 527           <para>When used with <command>enable</command>,
 528           <command>disable</command>, <command>edit</command>,
 529           (and related commands), make changes only temporarily, so
 530           that they are lost on the next reboot. This will have the
 531           effect that changes are not made in subdirectories of
 532           <filename>/etc</filename> but in <filename>/run</filename>,
 533           with identical immediate effects, however, since the latter
 534           is lost on reboot, the changes are lost too.</para>
 535
 536           <para>Similarly, when used with
 537           <command>set-property</command>, make changes only
 538           temporarily, so that they are lost on the next
 539           reboot.</para>
 540         </listitem>
 541       </varlistentry>
 542
 543       <varlistentry>
 544         <term><option>--preset-mode=</option></term>
 545
 546         <listitem>
 547           <para>Takes one of <literal>full</literal> (the default),
 548           <literal>enable-only</literal>,
 549           <literal>disable-only</literal>. When used with the
 550           <command>preset</command> or <command>preset-all</command>
 551           commands, controls whether units shall be disabled and
 552           enabled according to the preset rules, or only enabled, or
 553           only disabled.</para>
 554         </listitem>
 555       </varlistentry>
 556
 557       <varlistentry>
 558         <term><option>-n</option></term>
 559         <term><option>--lines=</option></term>
 560
 561         <listitem>
 562           <para>When used with <command>status</command>, controls the
 563           number of journal lines to show, counting from the most
 564           recent ones. Takes a positive integer argument. Defaults to
 565           10.</para>
 566         </listitem>
 567       </varlistentry>
 568
 569       <varlistentry>
 570         <term><option>-o</option></term>
 571         <term><option>--output=</option></term>
 572
 573         <listitem>
 574           <para>When used with <command>status</command>, controls the
 575           formatting of the journal entries that are shown. For the
 576           available choices, see
 577           <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 578           Defaults to <literal>short</literal>.</para>
 579         </listitem>
 580       </varlistentry>
 581
 582       <varlistentry>
 583         <term><option>--firmware-setup</option></term>
 584
 585         <listitem>
 586           <para>When used with the <command>reboot</command> command,
 587           indicate to the system's firmware to boot into setup
 588           mode. Note that this is currently only supported on some EFI
 589           systems and only if the system was booted in EFI
 590           mode.</para>
 591         </listitem>
 592       </varlistentry>
 593
 594       <varlistentry>
 595         <term><option>--plain</option></term>
 596
 597         <listitem>
 598           <para>When used with <command>list-dependencies</command>,
 599           the output is printed as a list instead of a tree.</para>
 600         </listitem>
 601       </varlistentry>
 602
 603       <xi:include href="user-system-options.xml" xpointer="host" />
 604       <xi:include href="user-system-options.xml" xpointer="machine" />
 605
 606       <xi:include href="standard-options.xml" xpointer="no-pager" />
 607       <xi:include href="standard-options.xml" xpointer="no-legend" />
 608       <xi:include href="standard-options.xml" xpointer="help" />
 609       <xi:include href="standard-options.xml" xpointer="version" />
 610     </variablelist>
 611   </refsect1>
 612
 613   <refsect1>
 614     <title>Commands</title>
 615
 616     <para>The following commands are understood:</para>
 617
 618     <refsect2>
 619       <title>Unit Commands</title>
 620
 621       <variablelist>
 622         <varlistentry>
 623           <term><command>list-units <optional><replaceable>PATTERN</replaceable>...</optional></command></term>
 624
 625           <listitem>
 626             <para>List known units (subject to limitations specified
 627             with <option>-t</option>). If one or more
 628             <replaceable>PATTERN</replaceable>s are specified, only
 629             units matching one of them are shown.</para>
 630
 631             <para>This is the default command.</para>
 632           </listitem>
 633         </varlistentry>
 634
 635         <varlistentry>
 636           <term><command>list-sockets <optional><replaceable>PATTERN</replaceable>...</optional></command></term>
 637
 638           <listitem>
 639             <para>List socket units ordered by listening address.
 640             If one or more <replaceable>PATTERN</replaceable>s are
 641             specified, only socket units matching one of them are
 642             shown. Produces output similar to
 643             <programlisting>
 644 LISTEN           UNIT                        ACTIVATES
 645 /dev/initctl     systemd-initctl.socket      systemd-initctl.service
 646 ...
 647 [::]:22          sshd.socket                 sshd.service
 648 kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
 649
 650 5 sockets listed.</programlisting>
 651             Note: because the addresses might contains spaces, this output
 652             is not suitable for programmatic consumption.
 653             </para>
 654
 655             <para>See also the options <option>--show-types</option>,
 656             <option>--all</option>, and <option>--state=</option>.</para>
 657           </listitem>
 658         </varlistentry>
 659
 660         <varlistentry>
 661           <term><command>list-timers <optional><replaceable>PATTERN</replaceable>...</optional></command></term>
 662
 663           <listitem>
 664             <para>List timer units ordered by the time they elapse
 665             next. If one or more <replaceable>PATTERN</replaceable>s
 666             are specified, only units matching one of them are shown.
 667             </para>
 668
 669             <para>See also the options <option>--all</option> and
 670             <option>--state=</option>.</para>
 671           </listitem>
 672         </varlistentry>
 673
 674         <varlistentry>
 675           <term><command>start <replaceable>PATTERN</replaceable>...</command></term>
 676
 677           <listitem>
 678             <para>Start (activate) one or more units specified on the
 679             command line.</para>
 680
 681             <para>Note that glob patterns operate on a list of currently
 682             loaded units. Units which are not active and are not in a
 683             failed state usually are not loaded, and would not be
 684             matched by any pattern. In addition, in case of
 685             instantiated units, systemd is often unaware of the
 686             instance name until the instance has been started. Therefore,
 687             using glob patterns with <command>start</command>
 688             has limited usefulness.</para>
 689           </listitem>
 690         </varlistentry>
 691         <varlistentry>
 692           <term><command>stop <replaceable>PATTERN</replaceable>...</command></term>
 693
 694           <listitem>
 695             <para>Stop (deactivate) one or more units specified on the
 696             command line.</para>
 697           </listitem>
 698         </varlistentry>
 699         <varlistentry>
 700           <term><command>reload <replaceable>PATTERN</replaceable>...</command></term>
 701
 702           <listitem>
 703             <para>Asks all units listed on the command line to reload
 704             their configuration. Note that this will reload the
 705             service-specific configuration, not the unit configuration
 706             file of systemd. If you want systemd to reload the
 707             configuration file of a unit, use the
 708             <command>daemon-reload</command> command. In other words:
 709             for the example case of Apache, this will reload Apache's
 710             <filename>httpd.conf</filename> in the web server, not the
 711             <filename>apache.service</filename> systemd unit
 712             file.</para>
 713
 714             <para>This command should not be confused with the
 715             <command>daemon-reload</command> command.</para>
 716           </listitem>
 717
 718         </varlistentry>
 719         <varlistentry>
 720           <term><command>restart <replaceable>PATTERN</replaceable>...</command></term>
 721
 722           <listitem>
 723             <para>Restart one or more units specified on the command
 724             line. If the units are not running yet, they will be
 725             started.</para>
 726           </listitem>
 727         </varlistentry>
 728         <varlistentry>
 729           <term><command>try-restart <replaceable>PATTERN</replaceable>...</command></term>
 730
 731           <listitem>
 732             <para>Restart one or more units specified on the command
 733             line if the units are running. This does nothing if units are not
 734             running.  Note that, for compatibility with Red Hat init
 735             scripts, <command>condrestart</command> is equivalent to this
 736             command.</para>
 737           </listitem>
 738         </varlistentry>
 739         <varlistentry>
 740           <term><command>reload-or-restart <replaceable>PATTERN</replaceable>...</command></term>
 741
 742           <listitem>
 743             <para>Reload one or more units if they support it. If not,
 744             restart them instead. If the units are not running yet, they
 745             will be started.</para>
 746           </listitem>
 747         </varlistentry>
 748         <varlistentry>
 749           <term><command>reload-or-try-restart <replaceable>PATTERN</replaceable>...</command></term>
 750
 751           <listitem>
 752             <para>Reload one or more units if they support it. If not,
 753             restart them instead. This does nothing if the units are not
 754             running. Note that, for compatibility with SysV init scripts,
 755             <command>force-reload</command> is equivalent to this
 756             command.</para>
 757           </listitem>
 758         </varlistentry>
 759         <varlistentry>
 760           <term><command>isolate <replaceable>NAME</replaceable></command></term>
 761
 762           <listitem>
 763             <para>Start the unit specified on the command line and its
 764             dependencies and stop all others. If a unit name with no
 765             extension is given, an extension of
 766             <literal>.target</literal> will be assumed.</para>
 767
 768             <para>This is similar to changing the runlevel in a
 769             traditional init system. The <command>isolate</command>
 770             command will immediately stop processes that are not enabled
 771             in the new unit, possibly including the graphical
 772             environment or terminal you are currently using.</para>
 773
 774             <para>Note that this is allowed only on units where
 775             <option>AllowIsolate=</option> is enabled. See
 776             <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 777             for details.</para>
 778           </listitem>
 779         </varlistentry>
 780         <varlistentry>
 781           <term><command>kill <replaceable>PATTERN</replaceable>...</command></term>
 782
 783           <listitem>
 784             <para>Send a signal to one or more processes of the
 785             unit. Use <option>--kill-who=</option> to select which
 786             process to kill. Use <option>--signal=</option> to select
 787             the signal to send.</para>
 788           </listitem>
 789         </varlistentry>
 790         <varlistentry>
 791           <term><command>is-active <replaceable>PATTERN</replaceable>...</command></term>
 792
 793           <listitem>
 794             <para>Check whether any of the specified units are active
 795             (i.e. running). Returns an exit code
 796             <constant>0</constant> if at least one is active, or
 797             non-zero otherwise. Unless <option>--quiet</option> is
 798             specified, this will also print the current unit state to
 799             standard output.</para>
 800           </listitem>
 801         </varlistentry>
 802         <varlistentry>
 803           <term><command>is-failed <replaceable>PATTERN</replaceable>...</command></term>
 804
 805           <listitem>
 806             <para>Check whether any of the specified units are in a
 807             "failed" state. Returns an exit code
 808             <constant>0</constant> if at least one has failed,
 809             non-zero otherwise. Unless <option>--quiet</option> is
 810             specified, this will also print the current unit state to
 811             standard output.</para>
 812           </listitem>
 813         </varlistentry>
 814         <varlistentry>
 815           <term><command>status</command> <optional><replaceable>PATTERN</replaceable>...|<replaceable>PID</replaceable>...]</optional></term>
 816
 817           <listitem>
 818             <para>Show terse runtime status information about one or
 819             more units, followed by most recent log data from the
 820             journal. If no units are specified, show system status. If
 821             combined with <option>--all</option>, also show the status of
 822             all units (subject to limitations specified with
 823             <option>-t</option>). If a PID is passed, show information
 824             about the unit the process belongs to.</para>
 825
 826             <para>This function is intended to generate human-readable
 827             output. If you are looking for computer-parsable output,
 828             use <command>show</command> instead. By default this
 829             function only shows 10 lines of output and ellipsizes
 830             lines to fit in the terminal window. This can be changes
 831             with <option>--lines</option> and <option>--full</option>,
 832             see above. In addition, <command>journalctl
 833             --unit=<replaceable>NAME</replaceable></command> or
 834             <command>journalctl
 835             --user-unit=<replaceable>NAME</replaceable></command> use
 836             a similar filter for messages and might be more
 837             convenient.
 838             </para>
 839           </listitem>
 840         </varlistentry>
 841         <varlistentry>
 842           <term><command>show</command> <optional><replaceable>PATTERN</replaceable>...|<replaceable>JOB</replaceable>...</optional></term>
 843
 844           <listitem>
 845             <para>Show properties of one or more units, jobs, or the
 846             manager itself. If no argument is specified, properties of
 847             the manager will be shown. If a unit name is specified,
 848             properties of the unit is shown, and if a job id is
 849             specified, properties of the job is shown. By default, empty
 850             properties are suppressed. Use <option>--all</option> to
 851             show those too. To select specific properties to show, use
 852             <option>--property=</option>. This command is intended to be
 853             used whenever computer-parsable output is required. Use
 854             <command>status</command> if you are looking for formatted
 855             human-readable output.</para>
 856           </listitem>
 857         </varlistentry>
 858         <varlistentry>
 859           <term><command>cat <replaceable>PATTERN</replaceable>...</command></term>
 860
 861           <listitem>
 862             <para>Show backing files of one or more units. Prints the
 863             "fragment" and "drop-ins" (source files) of units. Each
 864             file is preceded by a comment which includes the file
 865             name.</para>
 866           </listitem>
 867         </varlistentry>
 868         <varlistentry>
 869           <term><command>set-property <replaceable>NAME</replaceable> <replaceable>ASSIGNMENT</replaceable>...</command></term>
 870
 871           <listitem>
 872             <para>Set the specified unit properties at runtime where
 873             this is supported. This allows changing configuration
 874             parameter properties such as resource control settings at
 875             runtime. Not all properties may be changed at runtime, but
 876             many resource control settings (primarily those in
 877             <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>)
 878             may. The changes are applied instantly, and stored on disk
 879             for future boots, unless <option>--runtime</option> is
 880             passed, in which case the settings only apply until the
 881             next reboot. The syntax of the property assignment follows
 882             closely the syntax of assignments in unit files.</para>
 883
 884             <para>Example: <command>systemctl set-property foobar.service CPUShares=777</command></para>
 885
 886             <para>Note that this command allows changing multiple
 887             properties at the same time, which is preferable over
 888             setting them individually. Like unit file configuration
 889             settings, assigning the empty list to list parameters will
 890             reset the list.</para>
 891           </listitem>
 892         </varlistentry>
 893
 894         <varlistentry>
 895           <term><command>help <replaceable>PATTERN</replaceable>...|<replaceable>PID</replaceable>...</command></term>
 896
 897           <listitem>
 898             <para>Show manual pages for one or more units, if
 899             available. If a PID is given, the manual pages for the unit
 900             the process belongs to are shown.</para>
 901           </listitem>
 902         </varlistentry>
 903
 904         <varlistentry>
 905           <term><command>reset-failed [<replaceable>PATTERN</replaceable>...]</command></term>
 906
 907           <listitem>
 908             <para>Reset the <literal>failed</literal> state of the
 909             specified units, or if no unit name is passed, reset the state of all
 910             units. When a unit fails in some way (i.e. process exiting
 911             with non-zero error code, terminating abnormally or timing
 912             out), it will automatically enter the
 913             <literal>failed</literal> state and its exit code and status
 914             is recorded for introspection by the administrator until the
 915             service is restarted or reset with this command.</para>
 916           </listitem>
 917         </varlistentry>
 918
 919         <varlistentry>
 920           <term>
 921             <command>list-dependencies</command>
 922             <optional><replaceable>NAME</replaceable></optional>
 923           </term>
 924
 925           <listitem>
 926             <para>Shows units required and wanted by the specified
 927             unit. This recursively lists units following the
 928             <varname>Requires=</varname>,
 929             <varname>RequiresOverridable=</varname>,
 930             <varname>Requisite=</varname>,
 931             <varname>RequisiteOverridable=</varname>,
 932             <varname>ConsistsOf=</varname>,
 933             <varname>Wants=</varname>, <varname>BindsTo=</varname>
 934             dependencies. If no unit is specified,
 935             <filename>default.target</filename> is implied.</para>
 936
 937             <para>By default, only target units are recursively
 938             expanded. When <option>--all</option> is passed, all other
 939             units are recursively expanded as well.</para>
 940
 941             <para>Options <option>--reverse</option>,
 942             <option>--after</option>, <option>--before</option>
 943             may be used to change what types of dependencies
 944             are shown.</para>
 945           </listitem>
 946         </varlistentry>
 947       </variablelist>
 948     </refsect2>
 949
 950     <refsect2>
 951       <title>Unit File Commands</title>
 952
 953       <variablelist>
 954         <varlistentry>
 955           <term><command>list-unit-files <optional><replaceable>PATTERN...</replaceable></optional></command></term>
 956
 957           <listitem>
 958             <para>List installed unit files. If one or more
 959             <replaceable>PATTERN</replaceable>s are specified, only
 960             units whose filename (just the last component of the path)
 961             matches one of them are shown.</para>
 962           </listitem>
 963         </varlistentry>
 964
 965         <varlistentry>
 966           <term><command>enable <replaceable>NAME</replaceable>...</command></term>
 967
 968           <listitem>
 969             <para>Enable one or more unit files or unit file instances,
 970             as specified on the command line. This will create a number
 971             of symlinks as encoded in the <literal>[Install]</literal>
 972             sections of the unit files. After the symlinks have been
 973             created, the systemd configuration is reloaded (in a way that
 974             is equivalent to <command>daemon-reload</command>) to ensure
 975             the changes are taken into account immediately. Note that
 976             this does <emphasis>not</emphasis> have the effect of also
 977             starting any of the units being enabled. If this
 978             is desired, either <option>--now</option> should be used
 979             together with this command, or an additional <command>start</command>
 980             command must be invoked for the unit. Also note that in case of
 981             instance enablement, symlinks named the same as instances
 982             are created in the install location, however they all point to the
 983             same template unit file.</para>
 984
 985             <para>This command will print the actions executed. This
 986             output may be suppressed by passing <option>--quiet</option>.
 987             </para>
 988
 989             <para>Note that this operation creates only the suggested
 990             symlinks for the units. While this command is the
 991             recommended way to manipulate the unit configuration
 992             directory, the administrator is free to make additional
 993             changes manually by placing or removing symlinks in the
 994             directory. This is particularly useful to create
 995             configurations that deviate from the suggested default
 996             installation. In this case, the administrator must make sure
 997             to invoke <command>daemon-reload</command> manually as
 998             necessary to ensure the changes are taken into account.
 999             </para>
1000
1001             <para>Enabling units should not be confused with starting
1002             (activating) units, as done by the <command>start</command>
1003             command. Enabling and starting units is orthogonal: units
1004             may be enabled without being started and started without
1005             being enabled. Enabling simply hooks the unit into various
1006             suggested places (for example, so that the unit is
1007             automatically started on boot or when a particular kind of
1008             hardware is plugged in). Starting actually spawns the daemon
1009             process (in case of service units), or binds the socket (in
1010             case of socket units), and so on.</para>
1011
1012             <para>Depending on whether <option>--system</option>,
1013             <option>--user</option>, <option>--runtime</option>,
1014             or <option>--global</option> is specified, this enables the unit
1015             for the system, for the calling user only, for only this boot of
1016             the system, or for all future logins of all users, or only this
1017             boot.  Note that in the last case, no systemd daemon
1018             configuration is reloaded.</para>
1019
1020             <para>Using <command>enable</command> on masked units
1021             results in an error.</para>
1022           </listitem>
1023         </varlistentry>
1024
1025         <varlistentry>
1026           <term><command>disable <replaceable>NAME</replaceable>...</command></term>
1027
1028           <listitem>
1029             <para>Disables one or more units. This removes all symlinks
1030             to the specified unit files from the unit configuration
1031             directory, and hence undoes the changes made by
1032             <command>enable</command>. Note however that this removes
1033             all symlinks to the unit files (i.e. including manual
1034             additions), not just those actually created by
1035             <command>enable</command>. This call implicitly reloads the
1036             systemd daemon configuration after completing the disabling
1037             of the units. Note that this command does not implicitly
1038             stop the units that are being disabled. If this is desired, either
1039             <option>--now</option> should be used together with this command, or
1040             an additional <command>stop</command> command should be executed
1041             afterwards.</para>
1042
1043             <para>This command will print the actions executed. This
1044             output may be suppressed by passing <option>--quiet</option>.
1045             </para>
1046
1047             <para>This command honors <option>--system</option>,
1048             <option>--user</option>, <option>--runtime</option> and
1049             <option>--global</option> in a similar way as
1050             <command>enable</command>.</para>
1051           </listitem>
1052         </varlistentry>
1053
1054         <varlistentry>
1055           <term><command>reenable <replaceable>NAME</replaceable>...</command></term>
1056
1057           <listitem>
1058             <para>Reenable one or more unit files, as specified on the
1059             command line. This is a combination of
1060             <command>disable</command> and <command>enable</command> and
1061             is useful to reset the symlinks a unit is enabled with to
1062             the defaults configured in the <literal>[Install]</literal>
1063             section of the unit file.</para>
1064           </listitem>
1065         </varlistentry>
1066
1067         <varlistentry>
1068           <term><command>preset <replaceable>NAME</replaceable>...</command></term>
1069
1070           <listitem>
1071             <para>Reset one or more unit files, as specified on the
1072             command line, to the defaults configured in the preset
1073             policy files. This has the same effect as
1074             <command>disable</command> or <command>enable</command>,
1075             depending how the unit is listed in the preset files.</para>
1076
1077             <para>Use <option>--preset-mode=</option> to control
1078             whether units shall be enabled and disabled, or only
1079             enabled, or only disabled.</para>
1080
1081             <para>For more information on the preset policy format,
1082             see
1083             <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
1084             For more information on the concept of presets, please
1085             consult the <ulink
1086             url="http://freedesktop.org/wiki/Software/systemd/Preset">Preset</ulink>
1087             document.</para>
1088           </listitem>
1089         </varlistentry>
1090
1091         <varlistentry>
1092           <term><command>preset-all</command></term>
1093
1094           <listitem>
1095             <para>Resets all installed unit files to the defaults
1096             configured in the preset policy file (see above).</para>
1097
1098             <para>Use <option>--preset-mode=</option> to control
1099             whether units shall be enabled and disabled, or only
1100             enabled, or only disabled.</para>
1101           </listitem>
1102         </varlistentry>
1103
1104         <varlistentry>
1105           <term><command>is-enabled <replaceable>NAME</replaceable>...</command></term>
1106
1107           <listitem>
1108             <para>Checks whether any of the specified unit files are
1109             enabled (as with <command>enable</command>). Returns an
1110             exit code of 0 if at least one is enabled, non-zero
1111             otherwise. Prints the current enable status (see table).
1112             To suppress this output, use <option>--quiet</option>.
1113             </para>
1114
1115             <table>
1116               <title>
1117                 <command>is-enabled</command> output
1118               </title>
1119
1120               <tgroup cols='3'>
1121                 <thead>
1122                   <row>
1123                     <entry>Printed string</entry>
1124                     <entry>Meaning</entry>
1125                     <entry>Return value</entry>
1126                   </row>
1127                 </thead>
1128                 <tbody>
1129                   <row>
1130                     <entry><literal>enabled</literal></entry>
1131                     <entry morerows='1'>Enabled through a symlink in <filename>.wants</filename> directory (permanently or just in <filename>/run</filename>).</entry>
1132                     <entry morerows='1'>0</entry>
1133                   </row>
1134                   <row>
1135                     <entry><literal>enabled-runtime</literal></entry>
1136                   </row>
1137                   <row>
1138                     <entry><literal>linked</literal></entry>
1139                     <entry morerows='1'>Made available through a symlink to the unit file (permanently or just in <filename>/run</filename>).</entry>
1140                     <entry morerows='1'>1</entry>
1141                   </row>
1142                   <row>
1143                     <entry><literal>linked-runtime</literal></entry>
1144                   </row>
1145                   <row>
1146                     <entry><literal>masked</literal></entry>
1147                     <entry morerows='1'>Disabled entirely (permanently or just in <filename>/run</filename>).</entry>
1148                     <entry morerows='1'>1</entry>
1149                   </row>
1150                   <row>
1151                     <entry><literal>masked-runtime</literal></entry>
1152                   </row>
1153                   <row>
1154                     <entry><literal>static</literal></entry>
1155                     <entry>Unit file is not enabled, and has no provisions for enabling in the <literal>[Install]</literal> section.</entry>
1156                     <entry>0</entry>
1157                   </row>
1158                   <row>
1159                     <entry><literal>indirect</literal></entry>
1160                     <entry>Unit file itself is not enabled, but it has a non-empty <varname>Also=</varname> setting in the <literal>[Install]</literal> section, listing other unit files that might be enabled.</entry>
1161                     <entry>0</entry>
1162                   </row>
1163                   <row>
1164                     <entry><literal>disabled</literal></entry>
1165                     <entry>Unit file is not enabled.</entry>
1166                     <entry>1</entry>
1167                   </row>
1168                 </tbody>
1169               </tgroup>
1170             </table>
1171
1172           </listitem>
1173         </varlistentry>
1174
1175         <varlistentry>
1176           <term><command>mask <replaceable>NAME</replaceable>...</command></term>
1177
1178           <listitem>
1179             <para>Mask one or more unit files, as specified on the
1180             command line. This will link these units to
1181             <filename>/dev/null</filename>, making it impossible to
1182             start them. This is a stronger version of
1183             <command>disable</command>, since it prohibits all kinds of
1184             activation of the unit, including enablement and manual
1185             activation. Use this option with care. This honors the
1186             <option>--runtime</option> option to only mask temporarily
1187             until the next reboot of the system. The <option>--now</option>
1188             option can be used to ensure that the units are also stopped.</para>
1189           </listitem>
1190         </varlistentry>
1191
1192         <varlistentry>
1193           <term><command>unmask <replaceable>NAME</replaceable>...</command></term>
1194
1195           <listitem>
1196             <para>Unmask one or more unit files, as specified on the
1197             command line. This will undo the effect of
1198             <command>mask</command>.</para>
1199           </listitem>
1200         </varlistentry>
1201
1202         <varlistentry>
1203           <term><command>link <replaceable>FILENAME</replaceable>...</command></term>
1204
1205           <listitem>
1206             <para>Link a unit file that is not in the unit file search
1207             paths into the unit file search path. This requires an
1208             absolute path to a unit file. The effect of this can be
1209             undone with <command>disable</command>. The effect of this
1210             command is that a unit file is available for
1211             <command>start</command> and other commands although it
1212             is not installed directly in the unit search path.</para>
1213           </listitem>
1214         </varlistentry>
1215
1216         <varlistentry>
1217           <term><command>add-wants <replaceable>TARGET</replaceable>
1218           <replaceable>NAME</replaceable>...</command></term>
1219           <term><command>add-requires <replaceable>TARGET</replaceable>
1220           <replaceable>NAME</replaceable>...</command></term>
1221
1222           <listitem>
1223             <para>Adds <literal>Wants=</literal> or <literal>Requires=</literal>
1224             dependency, respectively, to the specified
1225             <replaceable>TARGET</replaceable> for one or more units. </para>
1226
1227             <para>This command honors <option>--system</option>,
1228             <option>--user</option>, <option>--runtime</option> and
1229             <option>--global</option> in a similar way as
1230             <command>enable</command>.</para>
1231
1232           </listitem>
1233         </varlistentry>
1234
1235         <varlistentry>
1236           <term><command>edit <replaceable>NAME</replaceable>...</command></term>
1237
1238           <listitem>
1239             <para>Edit a drop-in snippet or a whole replacement file if
1240             <option>--full</option> is specified, to extend or override the
1241             specified unit.</para>
1242
1243             <para>Depending on whether <option>--system</option> (the default),
1244             <option>--user</option>, or <option>--global</option> is specified,
1245             this creates a drop-in file for each unit either for the system,
1246             for the calling user or for all futures logins of all users. Then,
1247             the editor (see the "Environment" section below) is invoked on
1248             temporary files which will be written to the real location if the
1249             editor exits successfully.</para>
1250
1251             <para>If <option>--full</option> is specified, this will copy the
1252             original units instead of creating drop-in files.</para>
1253
1254             <para>If <option>--runtime</option> is specified, the changes will
1255             be made temporarily in <filename>/run</filename> and they will be
1256             lost on the next reboot.</para>
1257
1258             <para>If the temporary file is empty upon exit the modification of
1259             the related unit is canceled</para>
1260
1261             <para>After the units have been edited, systemd configuration is
1262             reloaded (in a way that is equivalent to <command>daemon-reload</command>).
1263             </para>
1264
1265             <para>Note that this command cannot be used to remotely edit units
1266             and that you cannot temporarily edit units which are in
1267             <filename>/etc</filename> since they take precedence over
1268             <filename>/run</filename>.</para>
1269           </listitem>
1270         </varlistentry>
1271
1272         <varlistentry>
1273           <term><command>get-default</command></term>
1274
1275           <listitem>
1276             <para>Return the default target to boot into. This returns
1277             the target unit name <filename>default.target</filename>
1278             is aliased (symlinked) to.</para>
1279           </listitem>
1280         </varlistentry>
1281
1282         <varlistentry>
1283           <term><command>set-default <replaceable>NAME</replaceable></command></term>
1284
1285           <listitem>
1286             <para>Set the default target to boot into. This sets
1287             (symlinks) the <filename>default.target</filename> alias
1288             to the given target unit.</para>
1289           </listitem>
1290         </varlistentry>
1291
1292       </variablelist>
1293     </refsect2>
1294
1295     <refsect2>
1296       <title>Machine Commands</title>
1297
1298       <variablelist>
1299         <varlistentry>
1300           <term><command>list-machines <optional><replaceable>PATTERN</replaceable>...</optional></command></term>
1301
1302           <listitem>
1303             <para>List the host and all running local containers with
1304             their state. If one or more
1305             <replaceable>PATTERN</replaceable>s are specified, only
1306             containers matching one of them are shown.
1307             </para>
1308           </listitem>
1309         </varlistentry>
1310       </variablelist>
1311     </refsect2>
1312
1313     <refsect2>
1314       <title>Job Commands</title>
1315
1316       <variablelist>
1317         <varlistentry>
1318           <term><command>list-jobs <optional><replaceable>PATTERN...</replaceable></optional></command></term>
1319
1320           <listitem>
1321             <para>List jobs that are in progress. If one or more
1322             <replaceable>PATTERN</replaceable>s are specified, only
1323             jobs for units matching one of them are shown.</para>
1324           </listitem>
1325         </varlistentry>
1326         <varlistentry>
1327           <term><command>cancel <replaceable>JOB</replaceable>...</command></term>
1328
1329           <listitem>
1330             <para>Cancel one or more jobs specified on the command line
1331             by their numeric job IDs. If no job ID is specified, cancel
1332             all pending jobs.</para>
1333           </listitem>
1334         </varlistentry>
1335       </variablelist>
1336     </refsect2>
1337
1338     <refsect2>
1339       <title>Snapshot Commands</title>
1340
1341       <variablelist>
1342         <varlistentry>
1343           <term><command>snapshot <optional><replaceable>NAME</replaceable></optional></command></term>
1344
1345           <listitem>
1346             <para>Create a snapshot. If a snapshot name is specified,
1347             the new snapshot will be named after it. If none is
1348             specified, an automatic snapshot name is generated. In
1349             either case, the snapshot name used is printed to standard
1350             output, unless <option>--quiet</option> is specified.
1351             </para>
1352
1353             <para>A snapshot refers to a saved state of the systemd
1354             manager. It is implemented itself as a unit that is
1355             generated dynamically with this command and has dependencies
1356             on all units active at the time. At a later time, the user
1357             may return to this state by using the
1358             <command>isolate</command> command on the snapshot unit.
1359             </para>
1360
1361             <para>Snapshots are only useful for saving and restoring
1362             which units are running or are stopped, they do not
1363             save/restore any other state. Snapshots are dynamic and lost
1364             on reboot.</para>
1365           </listitem>
1366         </varlistentry>
1367         <varlistentry>
1368           <term><command>delete <replaceable>PATTERN</replaceable>...</command></term>
1369
1370           <listitem>
1371             <para>Remove a snapshot previously created with
1372             <command>snapshot</command>.</para>
1373           </listitem>
1374         </varlistentry>
1375       </variablelist>
1376     </refsect2>
1377
1378     <refsect2>
1379       <title>Environment Commands</title>
1380
1381       <variablelist>
1382         <varlistentry>
1383           <term><command>show-environment</command></term>
1384
1385           <listitem>
1386             <para>Dump the systemd manager environment block. The
1387             environment block will be dumped in straight-forward form
1388             suitable for sourcing into a shell script. This environment
1389             block will be passed to all processes the manager
1390             spawns.</para>
1391           </listitem>
1392         </varlistentry>
1393         <varlistentry>
1394           <term><command>set-environment <replaceable>VARIABLE=VALUE</replaceable>...</command></term>
1395
1396           <listitem>
1397             <para>Set one or more systemd manager environment variables,
1398             as specified on the command line.</para>
1399           </listitem>
1400         </varlistentry>
1401         <varlistentry>
1402           <term><command>unset-environment <replaceable>VARIABLE</replaceable>...</command></term>
1403
1404           <listitem>
1405             <para>Unset one or more systemd manager environment
1406             variables. If only a variable name is specified, it will be
1407             removed regardless of its value. If a variable and a value
1408             are specified, the variable is only removed if it has the
1409             specified value.</para>
1410           </listitem>
1411         </varlistentry>
1412         <varlistentry>
1413           <term>
1414             <command>import-environment</command>
1415             <optional><replaceable>VARIABLE...</replaceable></optional>
1416           </term>
1417
1418           <listitem>
1419             <para>Import all, one or more environment variables set on
1420             the client into the systemd manager environment block. If
1421             no arguments are passed, the entire environment block is
1422             imported. Otherwise, a list of one or more environment
1423             variable names should be passed, whose client-side values
1424             are then imported into the manager's environment
1425             block.</para>
1426           </listitem>
1427         </varlistentry>
1428       </variablelist>
1429     </refsect2>
1430
1431     <refsect2>
1432       <title>Manager Lifecycle Commands</title>
1433
1434       <variablelist>
1435         <varlistentry>
1436           <term><command>daemon-reload</command></term>
1437
1438           <listitem>
1439             <para>Reload systemd manager configuration. This will
1440             rerun all generators (see
1441             <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>),
1442             reload all unit files, and recreate the entire dependency
1443             tree. While the daemon is being reloaded, all sockets
1444             systemd listens on behalf of user configuration will stay
1445             accessible.</para>
1446
1447             <para>This command should not be confused with the
1448             <command>reload</command> command.</para>
1449           </listitem>
1450         </varlistentry>
1451         <varlistentry>
1452           <term><command>daemon-reexec</command></term>
1453
1454           <listitem>
1455             <para>Reexecute the systemd manager. This will serialize the
1456             manager state, reexecute the process and deserialize the
1457             state again. This command is of little use except for
1458             debugging and package upgrades. Sometimes, it might be
1459             helpful as a heavy-weight <command>daemon-reload</command>.
1460             While the daemon is being reexecuted, all sockets systemd listening
1461             on behalf of user configuration will stay accessible.
1462             </para>
1463           </listitem>
1464         </varlistentry>
1465       </variablelist>
1466     </refsect2>
1467
1468     <refsect2>
1469       <title>System Commands</title>
1470
1471       <variablelist>
1472         <varlistentry>
1473           <term><command>is-system-running</command></term>
1474
1475           <listitem>
1476             <para>Checks whether the system is operational. This
1477             returns success when the system is fully up and running,
1478             meaning not in startup, shutdown or maintenance
1479             mode. Failure is returned otherwise. In addition, the
1480             current state is printed in a short string to standard
1481             output, see table below. Use <option>--quiet</option> to
1482             suppress this output.</para>
1483
1484             <table>
1485               <title>Manager Operational States</title>
1486               <tgroup cols='2'>
1487                 <colspec colname='name' />
1488                 <colspec colname='description' />
1489                 <thead>
1490                   <row>
1491                     <entry>Name</entry>
1492                     <entry>Description</entry>
1493                   </row>
1494                 </thead>
1495                 <tbody>
1496                   <row>
1497                     <entry><varname>initializing</varname></entry>
1498                     <entry><para>Early bootup, before
1499                     <filename>basic.target</filename> is reached
1500                     or the <varname>maintenance</varname> state entered.
1501                     </para></entry>
1502                   </row>
1503                   <row>
1504                     <entry><varname>starting</varname></entry>
1505                     <entry><para>Late bootup, before the job queue
1506                     becomes idle for the first time, or one of the
1507                     rescue targets are reached.</para></entry>
1508                   </row>
1509                   <row>
1510                     <entry><varname>running</varname></entry>
1511                     <entry><para>The system is fully
1512                     operational.</para></entry>
1513                   </row>
1514                   <row>
1515                     <entry><varname>degraded</varname></entry>
1516                     <entry><para>The system is operational but one or more
1517                     units failed.</para></entry>
1518                   </row>
1519                   <row>
1520                     <entry><varname>maintenance</varname></entry>
1521                     <entry><para>The rescue or emergency target is
1522                     active.</para></entry>
1523                   </row>
1524                   <row>
1525                     <entry><varname>stopping</varname></entry>
1526                     <entry><para>The manager is shutting
1527                     down.</para></entry>
1528                   </row>
1529                 </tbody>
1530               </tgroup>
1531             </table>
1532           </listitem>
1533         </varlistentry>
1534
1535         <varlistentry>
1536           <term><command>default</command></term>
1537
1538           <listitem>
1539             <para>Enter default mode. This is mostly equivalent to
1540             <command>isolate default.target</command>.</para>
1541           </listitem>
1542         </varlistentry>
1543
1544         <varlistentry>
1545           <term><command>rescue</command></term>
1546
1547           <listitem>
1548             <para>Enter rescue mode. This is mostly equivalent to
1549             <command>isolate rescue.target</command>, but also prints a
1550             wall message to all users.</para>
1551           </listitem>
1552         </varlistentry>
1553         <varlistentry>
1554           <term><command>emergency</command></term>
1555
1556           <listitem>
1557             <para>Enter emergency mode. This is mostly equivalent to
1558             <command>isolate emergency.target</command>, but also prints
1559             a wall message to all users.</para>
1560           </listitem>
1561         </varlistentry>
1562         <varlistentry>
1563           <term><command>halt</command></term>
1564
1565           <listitem>
1566             <para>Shut down and halt the system. This is mostly equivalent to
1567             <command>start halt.target --job-mode=replace-irreversibly</command>, but also
1568             prints a wall message to all users.  If combined with
1569             <option>--force</option>, shutdown of all running services is
1570             skipped, however all processes are killed and all file
1571             systems are unmounted or mounted read-only, immediately
1572             followed by the system halt.  If <option>--force</option> is
1573             specified twice, the operation is immediately executed
1574             without terminating any processes or unmounting any file
1575             systems. This may result in data loss.</para>
1576           </listitem>
1577         </varlistentry>
1578         <varlistentry>
1579           <term><command>poweroff</command></term>
1580
1581           <listitem>
1582             <para>Shut down and power-off the system. This is mostly
1583             equivalent to <command>start poweroff.target --job-mode=replace-irreversibly</command>,
1584             but also prints a wall message to all users. If combined with
1585             <option>--force</option>, shutdown of all running services is
1586             skipped, however all processes are killed and all file
1587             systems are unmounted or mounted read-only, immediately
1588             followed by the powering off. If <option>--force</option> is
1589             specified twice, the operation is immediately executed
1590             without terminating any processes or unmounting any file
1591             systems. This may result in data loss.</para>
1592           </listitem>
1593         </varlistentry>
1594         <varlistentry>
1595           <term><command>reboot <optional><replaceable>arg</replaceable></optional></command></term>
1596
1597           <listitem>
1598             <para>Shut down and reboot the system. This is mostly
1599             equivalent to <command>start reboot.target --job-mode=replace-irreversibly</command>,
1600             but also prints a wall message to all users. If combined with
1601             <option>--force</option>, shutdown of all running services is
1602             skipped, however all processes are killed and all file
1603             systems are unmounted or mounted read-only, immediately
1604             followed by the reboot. If <option>--force</option> is
1605             specified twice, the operation is immediately executed
1606             without terminating any processes or unmounting any file
1607             systems. This may result in data loss.</para>
1608
1609             <para>If the optional argument
1610             <replaceable>arg</replaceable> is given, it will be passed
1611             as the optional argument to the
1612             <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
1613             system call. The value is architecture and firmware
1614             specific. As an example, <literal>recovery</literal> might
1615             be used to trigger system recovery, and
1616             <literal>fota</literal> might be used to trigger a
1617             <quote>firmware over the air</quote> update.</para>
1618           </listitem>
1619         </varlistentry>
1620
1621         <varlistentry>
1622           <term><command>kexec</command></term>
1623
1624           <listitem>
1625             <para>Shut down and reboot the system via kexec. This is
1626             mostly equivalent to <command>start kexec.target --job-mode=replace-irreversibly</command>,
1627             but also prints a wall message to all users. If combined
1628             with <option>--force</option>, shutdown of all running
1629             services is skipped, however all processes are killed and
1630             all file systems are unmounted or mounted read-only,
1631             immediately followed by the reboot.</para>
1632           </listitem>
1633         </varlistentry>
1634
1635         <varlistentry>
1636           <term><command>exit <optional><replaceable>EXIT_CODE</replaceable></optional></command></term>
1637
1638           <listitem>
1639             <para>Ask the systemd manager to quit. This is only
1640             supported for user service managers (i.e. in conjunction
1641             with the <option>--user</option> option) or in containers
1642             and is equivalent to <command>poweroff</command> otherwise.</para>
1643
1644             <para>The systemd manager can exit with a non-zero exit
1645             code if the optional argument
1646             <replaceable>EXIT_CODE</replaceable> is given.</para>
1647           </listitem>
1648         </varlistentry>
1649
1650         <varlistentry>
1651           <term><command>switch-root <replaceable>ROOT</replaceable> <optional><replaceable>INIT</replaceable></optional></command></term>
1652
1653           <listitem>
1654             <para>Switches to a different root directory and executes a
1655             new system manager process below it. This is intended for
1656             usage in initial RAM disks ("initrd"), and will transition
1657             from the initrd's system manager process (a.k.a "init"
1658             process) to the main system manager process. This call takes two
1659             arguments: the directory that is to become the new root directory, and
1660             the path to the new system manager binary below it to
1661             execute as PID 1. If the latter is omitted or the empty
1662             string, a systemd binary will automatically be searched for
1663             and used as init. If the system manager path is omitted or
1664             equal to the empty string, the state of the initrd's system
1665             manager process is passed to the main system manager, which
1666             allows later introspection of the state of the services
1667             involved in the initrd boot.</para>
1668           </listitem>
1669         </varlistentry>
1670
1671         <varlistentry>
1672           <term><command>suspend</command></term>
1673
1674           <listitem>
1675             <para>Suspend the system. This will trigger activation of
1676             the special <filename>suspend.target</filename> target.
1677             </para>
1678           </listitem>
1679         </varlistentry>
1680
1681         <varlistentry>
1682           <term><command>hibernate</command></term>
1683
1684           <listitem>
1685             <para>Hibernate the system. This will trigger activation of
1686             the special <filename>hibernate.target</filename> target.
1687             </para>
1688           </listitem>
1689         </varlistentry>
1690
1691         <varlistentry>
1692           <term><command>hybrid-sleep</command></term>
1693
1694           <listitem>
1695             <para>Hibernate and suspend the system. This will trigger
1696             activation of the special
1697             <filename>hybrid-sleep.target</filename> target.</para>
1698           </listitem>
1699         </varlistentry>
1700       </variablelist>
1701     </refsect2>
1702
1703     <refsect2>
1704       <title>Parameter Syntax</title>
1705
1706       <para>Unit commands listed above take either a single unit name
1707       (designated as <replaceable>NAME</replaceable>), or multiple
1708       unit specifications (designated as
1709       <replaceable>PATTERN</replaceable>...). In the first case, the
1710       unit name with or without a suffix must be given. If the suffix
1711       is not specified, systemctl will append a suitable suffix,
1712       <literal>.service</literal> by default, and a type-specific
1713       suffix in case of commands which operate only on specific unit
1714       types. For example,
1715       <programlisting># systemctl start sshd</programlisting> and
1716       <programlisting># systemctl start sshd.service</programlisting>
1717       are equivalent, as are
1718       <programlisting># systemctl isolate default</programlisting>
1719       and
1720       <programlisting># systemctl isolate default.target</programlisting>
1721       Note that (absolute) paths to device nodes are automatically
1722       converted to device unit names, and other (absolute) paths to
1723       mount unit names.
1724       <programlisting># systemctl status /dev/sda
1725 # systemctl status /home</programlisting>
1726       are equivalent to:
1727       <programlisting># systemctl status dev-sda.device
1728 # systemctl status home.mount</programlisting>
1729       In the second case, shell-style globs will be matched against
1730       currently loaded units; literal unit names, with or without
1731       a suffix, will be treated as in the first case. This means that
1732       literal unit names always refer to exactly one unit, but globs
1733       may match zero units and this is not considered an error.</para>
1734
1735       <para>Glob patterns use
1736       <citerefentry project='man-pages'><refentrytitle>fnmatch</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
1737       so normal shell-style globbing rules are used, and
1738       <literal>*</literal>, <literal>?</literal>,
1739       <literal>[]</literal> may be used. See
1740       <citerefentry project='man-pages'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>
1741       for more details. The patterns are matched against the names of
1742       currently loaded units, and patterns which do not match anything
1743       are silently skipped. For example:
1744       <programlisting># systemctl stop sshd@*.service</programlisting>
1745       will stop all <filename>sshd@.service</filename> instances.
1746       </para>
1747
1748       <para>For unit file commands, the specified
1749       <replaceable>NAME</replaceable> should be the full name of the
1750       unit file, or the absolute path to the unit file:
1751       <programlisting># systemctl enable foo.service</programlisting>
1752       or
1753       <programlisting># systemctl link /path/to/foo.service</programlisting>
1754       </para>
1755     </refsect2>
1756
1757   </refsect1>
1758
1759   <refsect1>
1760     <title>Exit status</title>
1761
1762     <para>On success, 0 is returned, a non-zero failure
1763     code otherwise.</para>
1764   </refsect1>
1765
1766   <refsect1>
1767     <title>Environment</title>
1768
1769     <variablelist class='environment-variables'>
1770       <varlistentry>
1771         <term><varname>$SYSTEMD_EDITOR</varname></term>
1772
1773         <listitem><para>Editor to use when editing units; overrides
1774         <varname>$EDITOR</varname> and <varname>$VISUAL</varname>. If neither
1775         <varname>$SYSTEMD_EDITOR</varname> nor <varname>$EDITOR</varname> nor
1776         <varname>$VISUAL</varname> are present or if it is set to an empty
1777         string or if their execution failed, systemctl will try to execute well
1778         known editors in this order:
1779         <citerefentry project='die-net'><refentrytitle>editor</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1780         <citerefentry project='die-net'><refentrytitle>nano</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1781         <citerefentry project='die-net'><refentrytitle>vim</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1782         <citerefentry project='die-net'><refentrytitle>vi</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
1783         </para></listitem>
1784       </varlistentry>
1785     </variablelist>
1786     <xi:include href="less-variables.xml" xpointer="pager"/>
1787     <xi:include href="less-variables.xml" xpointer="less"/>
1788   </refsect1>
1789
1790   <refsect1>
1791     <title>See Also</title>
1792     <para>
1793       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1794       <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1795       <citerefentry><refentrytitle>loginctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1796       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1797       <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1798       <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1799       <citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1800       <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1801       <citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1802       <citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
1803       <citerefentry project='man-pages'><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>
1804     </para>
1805   </refsect1>
1806
1807 </refentry>