<?xml version='1.0'?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY % entities SYSTEM "custom-entities.ent" >
%entities;
]>
-
-<!--
- SPDX-License-Identifier: LGPL-2.1+
--->
+<!-- SPDX-License-Identifier: LGPL-2.1+ -->
<refentry id="systemctl"
xmlns:xi="http://www.w3.org/2001/XInclude">
<para>When listing units with <command>list-dependencies</command>, recursively show
dependencies of all dependent units (by default only dependencies of target units are
shown).</para>
+
+ <para>When used with <command>status</command>, show journal messages in full, even if they include
+ unprintable characters or are very long. By default, fields with unprintable characters are
+ abbreviated as "blob data". (Note that the pager may escape unprintable characters again.)</para>
</listitem>
</varlistentry>
</varlistentry>
+ <varlistentry>
+ <term><option>-T</option></term>
+ <term><option>--show-transaction</option></term>
+
+ <listitem>
+ <para>When enqueuing a unit job (for example as effect of a <command>systemctl start</command>
+ invocation or similar), show brief information about all jobs enqueued, covering both the requested
+ job and any added because of unit dependencies. Note that the output will only include jobs
+ immediately part of the transaction requested. It is possible that service start-up program code
+ run as effect of the enqueued jobs might request further jobs to be pulled in. This means that
+ completion of the listed jobs might ultimately entail more jobs than the listed ones.</para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>--fail</option></term>
<term><option>--ignore-inhibitors</option></term>
<listitem>
- <para>When system shutdown or a sleep state is requested,
- ignore inhibitor locks. Applications can establish inhibitor
- locks to avoid that certain important operations (such as CD
- burning or suchlike) are interrupted by system shutdown or a
- sleep state. Any user may take these locks and privileged
- users may override these locks. If any locks are taken,
- shutdown and sleep state requests will normally fail
- (regardless of whether privileged or not) and a list of active locks
- is printed. However, if <option>--ignore-inhibitors</option>
- is specified, the locks are ignored and not printed, and the
- operation attempted anyway, possibly requiring additional
- privileges.</para>
+ <para>When system shutdown or a sleep state is requested, ignore inhibitor locks. Applications can establish
+ inhibitor locks to avoid that certain important operations (such as CD burning or suchlike) are interrupted
+ by system shutdown or a sleep state. Any user may take these locks and privileged users may override these
+ locks. If any locks are taken, shutdown and sleep state requests will normally fail (unless privileged) and a
+ list of active locks is printed. However, if <option>--ignore-inhibitors</option> is specified, the
+ established locks are ignored and not shown, and the operation attempted anyway, possibly requiring
+ additional privileges.</para>
</listitem>
</varlistentry>
<listitem>
<para>Just print what would be done. Currently supported by verbs
<command>halt</command>, <command>poweroff</command>, <command>reboot</command>,
- <command>kexec</command>, <command>suspend</command>,
- <command>hibernate</command>, <command>hybrid-sleep</command>,
+ <command>kexec</command>, <command>suspend</command>, <command>hibernate</command>,
+ <command>hybrid-sleep</command>, <command>suspend-then-hibernate</command>,
<command>default</command>, <command>rescue</command>,
<command>emergency</command>, and <command>exit</command>.</para>
</listitem>
Note that this will wait forever if any given unit never terminates
(by itself or by getting stopped explicitly); particularly services
which use <literal>RemainAfterExit=yes</literal>.</para>
+
+ <para>When used with <command>is-system-running</command>, wait
+ until the boot process is completed before returning.</para>
</listitem>
</varlistentry>
<term><option>--runtime</option></term>
<listitem>
- <para>When used with <command>set-property</command>, make changes only
- temporarily, so that they are lost on the next reboot.</para>
-
- <para>Similarily, when used with <command>enable</command>, <command>mask</command>,
- <command>edit</command> and related commands, make temporary changes, which are lost on
- the next reboot. Changes are not made in subdirectories of <filename>/etc</filename>, but
- in <filename>/run</filename>. The immediate effect is identical, however since the latter
+ <para>When used with <command>enable</command>,
+ <command>disable</command>, <command>edit</command>,
+ (and related commands), make changes only temporarily, so
+ that they are lost on the next reboot. This will have the
+ effect that changes are not made in subdirectories of
+ <filename>/etc</filename> but in <filename>/run</filename>,
+ with identical immediate effects, however, since the latter
is lost on reboot, the changes are lost too.</para>
- <para>Note: this option cannot be used with <command>disable</command>,
- <command>unmask</command>, <command>preset</command>, or <command>preset-all</command>,
- because those operations sometimes need to remove symlinks under <filename>/etc</filename>
- to have the desired effect, which would cause a persistent change.</para>
+ <para>Similarly, when used with
+ <command>set-property</command>, make changes only
+ temporarily, so that they are lost on the next
+ reboot.</para>
</listitem>
</varlistentry>
<term><option>--lines=</option></term>
<listitem>
- <para>When used with <command>status</command>, controls the
- number of journal lines to show, counting from the most
- recent ones. Takes a positive integer argument. Defaults to
+ <para>When used with <command>status</command>, controls the number of journal lines to show, counting from
+ the most recent ones. Takes a positive integer argument, or 0 to disable journal output. Defaults to
10.</para>
</listitem>
</varlistentry>
<term><option>--firmware-setup</option></term>
<listitem>
- <para>When used with the <command>reboot</command> command,
- indicate to the system's firmware to boot into setup
- mode. Note that this is currently only supported on some EFI
- systems and only if the system was booted in EFI
- mode.</para>
+ <para>When used with the <command>reboot</command> command, indicate to the system's firmware to reboot into
+ the firmware setup interface. Note that this functionality is not available on all systems.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--boot-loader-menu=</option></term>
+
+ <listitem>
+ <para>When used with the <command>reboot</command> command, indicate to the system's boot loader to show the
+ boot loader menu on the following boot. Takes a time value as parameter — indicating the menu time-out. Pass
+ zero in order to disable the menu time-out. Note that not all boot loaders support this
+ functionality.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><option>--boot-loader-entry=</option></term>
+
+ <listitem>
+ <para>When used with the <command>reboot</command> command, indicate to the system's boot loader to boot into
+ a specific boot loader entry on the following boot. Takes a boot loader entry identifier as argument, or
+ <literal>help</literal> in order to list available entries. Note that not all boot loaders support this
+ functionality.</para>
</listitem>
</varlistentry>
<variablelist>
<varlistentry>
- <term><command>list-units <optional><replaceable>PATTERN</replaceable>…</optional></command></term>
+ <term><command>list-units</command> <optional><replaceable>PATTERN</replaceable>…</optional></term>
<listitem>
<para>List units that <command>systemd</command> currently has in memory. This includes units that are
boot-efi.mount loaded active mounted /boot/efi
systemd-journald.service loaded active running Journal Service
systemd-logind.service loaded active running Login Service
-● user@1000.service loaded active running User Manager for UID 1000
-…
+● user@1000.service loaded failed failed User Manager for UID 1000
+ …
systemd-tmpfiles-clean.timer loaded active waiting Daily Cleanup of Temporary Directories
LOAD = Reflects whether the unit definition was properly loaded.
</varlistentry>
<varlistentry>
- <term><command>list-sockets <optional><replaceable>PATTERN</replaceable>…</optional></command></term>
+ <term><command>list-sockets</command> <optional><replaceable>PATTERN</replaceable>…</optional></term>
<listitem>
<para>List socket units currently in memory, ordered by listening address. If one or more
</varlistentry>
<varlistentry>
- <term><command>list-timers <optional><replaceable>PATTERN</replaceable>…</optional></command></term>
+ <term><command>list-timers</command> <optional><replaceable>PATTERN</replaceable>…</optional></term>
<listitem>
<para>List timer units currently in memory, ordered by the time they elapse next. If one or more
<para>Note that restarting a unit with this command does not necessarily flush out all of the unit's
resources before it is started again. For example, the per-service file descriptor storage facility (see
- <varname>FileDescriptoreStoreMax=</varname> in
+ <varname>FileDescriptorStoreMax=</varname> in
<citerefentry><refentrytitle>systemd.service</refentrytitle><manvolnum>5</manvolnum></citerefentry>) will
remain intact as long as the unit has a job pending, and is only cleared when the unit is fully stopped and
no jobs are pending anymore. If it is intended that the file descriptor store is flushed out, too, during a
terminating abnormally or timing out), it will automatically enter the <literal>failed</literal> state and
its exit code and status is recorded for introspection by the administrator until the service is
stopped/re-started or reset with this command.</para>
+
+ <para>In addition to resetting the <literal>failed</literal> state of a unit it also resets various other
+ per-unit properties: the start rate limit counter of all unit types is reset to zero, as is the restart
+ counter of service units. Thus, if a unit's start limit (as configured with
+ <varname>StartLimitIntervalSec=</varname>/<varname>StartLimitBurst=</varname>) is hit and the unit refuses
+ to be started again, use this command to make it startable again.</para>
</listitem>
</varlistentry>
<option>--after</option>, <option>--before</option>
may be used to change what types of dependencies
are shown.</para>
+
+ <para>Note that this command only lists units currently loaded into memory by the service manager. In
+ particular, this command is not suitable to get a comprehensive list at all reverse dependencies on a
+ specific unit, as it won't list the dependencies declared by units currently not loaded.</para>
</listitem>
</varlistentry>
</variablelist>
<variablelist>
<varlistentry>
- <term><command>list-unit-files <optional><replaceable>PATTERN…</replaceable></optional></command></term>
+ <term><command>list-unit-files</command> <optional><replaceable>PATTERN…</replaceable></optional></term>
<listitem>
<para>List unit files installed on the system, in combination with their enablement state (as reported by
</row>
<row>
<entry><literal>indirect</literal></entry>
- <entry>The unit file itself is not enabled, but it has a non-empty <varname>Also=</varname> setting in the <literal>[Install]</literal> unit file section, listing other unit files that might be enabled, or it has an alias under a different name through a symlink that is not specified in Also=. For template unit file, an instance different than the one specified in <varname>DefaultInstance=</varname> is enabled.</entry>
+ <entry>The unit file itself is not enabled, but it has a non-empty <varname>Also=</varname> setting in the <literal>[Install]</literal> unit file section, listing other unit files that might be enabled, or it has an alias under a different name through a symlink that is not specified in <varname>Also=</varname>. For template unit file, an instance different than the one specified in <varname>DefaultInstance=</varname> is enabled.</entry>
<entry>0</entry>
</row>
<row>
<variablelist>
<varlistentry>
- <term><command>list-machines <optional><replaceable>PATTERN</replaceable>…</optional></command></term>
+ <term><command>list-machines</command> <optional><replaceable>PATTERN</replaceable>…</optional></term>
<listitem>
<para>List the host and all running local containers with
output, see the table below. Use <option>--quiet</option> to
suppress this output.</para>
+ <para>Use <option>--wait</option> to wait until the boot
+ process is completed before printing the current state and
+ returning the appropriate error status. If <option>--wait</option>
+ is in use, states <varname>initializing</varname> or
+ <varname>starting</varname> will not be reported, instead
+ the command will block until a later state (such as
+ <varname>running</varname> or <varname>degraded</varname>)
+ is reached.</para>
+
<table>
<title><command>is-system-running</command> output</title>
<tgroup cols='3'>
</listitem>
</varlistentry>
<varlistentry>
- <term><command>reboot <optional><replaceable>arg</replaceable></optional></command></term>
+ <term><command>reboot</command> <optional><replaceable>arg</replaceable></optional></term>
<listitem>
<para>Shut down and reboot the system. This is mostly equivalent to <command>systemctl start reboot.target
</varlistentry>
<varlistentry>
- <term><command>exit <optional><replaceable>EXIT_CODE</replaceable></optional></command></term>
+ <term><command>exit</command> <optional><replaceable>EXIT_CODE</replaceable></optional></term>
<listitem>
<para>Ask the service manager to quit. This is only supported for user service managers (i.e. in
</varlistentry>
<varlistentry>
- <term><command>switch-root <replaceable>ROOT</replaceable> <optional><replaceable>INIT</replaceable></optional></command></term>
+ <term><command>switch-root</command> <replaceable>ROOT</replaceable> <optional><replaceable>INIT</replaceable></optional></term>
<listitem>
<para>Switches to a different root directory and executes a new system manager process below it. This is
sleep operation is successfully enqueued. It will not wait for the sleep/wake-up cycle to complete.</para>
</listitem>
</varlistentry>
+
+ <varlistentry>
+ <term><command>suspend-then-hibernate</command></term>
+
+ <listitem>
+ <para>Suspend the system and hibernate it after the delay specified in <filename>systemd-sleep.conf</filename>.
+ This will trigger activation of the special target unit <filename>suspend-then-hibernate.target</filename>.
+ This command is asynchronous, and will return after the hybrid sleep operation is successfully enqueued.
+ It will not wait for the sleep/wake-up or hibernate/thaw cycle to complete.</para>
+ </listitem>
+ </varlistentry>
</variablelist>
</refsect2>
<refsect1>
<title>Exit status</title>
- <para>On success, 0 is returned, a non-zero failure
- code otherwise.</para>
+ <para>On success, 0 is returned, a non-zero failure code otherwise.</para>
+
+ <para><command>systemctl</command> uses the return codes defined by LSB, as defined in
+ <ulink url="http://refspecs.linuxbase.org/LSB_3.0.0/LSB-PDA/LSB-PDA/iniscrptact.html">LSB 3.0.0</ulink>.
+ </para>
+
+ <table>
+ <title>LSB return codes</title>
+
+ <tgroup cols='3'>
+ <thead>
+ <row>
+ <entry>Value</entry>
+ <entry>Description in LSB</entry>
+ <entry>Use in systemd</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><constant>0</constant></entry>
+ <entry>"program is running or service is OK"</entry>
+ <entry>unit is active</entry>
+ </row>
+ <row>
+ <entry><constant>1</constant></entry>
+ <entry>"program is dead and <filename>/var/run</filename> pid file exists"</entry>
+ <entry>unit <emphasis>not</emphasis> failed (used by <command>is-failed</command>)</entry>
+ </row>
+ <row>
+ <entry><constant>2</constant></entry>
+ <entry>"program is dead and <filename>/var/lock</filename> lock file exists"</entry>
+ <entry>unused</entry>
+ </row>
+ <row>
+ <entry><constant>3</constant></entry>
+ <entry>"program is not running"</entry>
+ <entry>unit is not active</entry>
+ </row>
+ <row>
+ <entry><constant>4</constant></entry>
+ <entry>"program or service status is unknown"</entry>
+ <entry>no such unit</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>The mapping of LSB service states to systemd unit states is imperfect, so it is better to
+ not rely on those return values but to look for specific unit states and substates instead.
+ </para>
</refsect1>
<refsect1>
projects / thirdparty / systemd.git / blobdiff