-<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
+<?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" [
<!ENTITY % entities SYSTEM "custom-entities.ent" >
<!--
SPDX-License-Identifier: LGPL-2.1+
-
- This file is part of systemd.
-
- Copyright 2010 Lennart Poettering
-
- systemd is free software; you can redistribute it and/or modify it
- under the terms of the GNU Lesser General Public License as published by
- the Free Software Foundation; either version 2.1 of the License, or
- (at your option) any later version.
-
- systemd is distributed in the hope that it will be useful, but
- WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- Lesser General Public License for more details.
-
- You should have received a copy of the GNU Lesser General Public License
- along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="systemctl"
<refentryinfo>
<title>systemctl</title>
<productname>systemd</productname>
-
- <authorgroup>
- <author>
- <contrib>Developer</contrib>
- <firstname>Lennart</firstname>
- <surname>Poettering</surname>
- <email>lennart@poettering.net</email>
- </author>
- </authorgroup>
</refentryinfo>
<refmeta>
<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>
<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>--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>
<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.
terminal supports that. A colored dot is shown next to services which
were masked, not found, or otherwise failed.</para>
- <para>The LOAD column shows the load state, one of
- <constant>loaded</constant>, <constant>not-found</constant>,
- <constant>stub</constant>, <constant>error</constant>,
- <constant>merged</constant>, <constant>masked</constant>. The ACTIVE
- columns shows the general unit state, one of <constant>active</constant>,
- <constant>reloading</constant>, <constant>inactive</constant>,
- <constant>failed</constant>, <constant>activating</constant>,
- <constant>deactivating</constant>. The SUB column shows the
- unit-type-specific detailed state of the unit, possible values vary by
- unit type. The list of possible LOAD, ACTIVE, and SUB states is not
- constant and new systemd releases may both add and remove values.
- <programlisting>systemctl --state=help</programlisting> command maybe be
- used to display the current set of possible values.</para>
+ <para>The LOAD column shows the load state, one of <constant>loaded</constant>,
+ <constant>not-found</constant>, <constant>bad-setting</constant>, <constant>error</constant>,
+ <constant>masked</constant>. The ACTIVE columns shows the general unit state, one of
+ <constant>active</constant>, <constant>reloading</constant>, <constant>inactive</constant>,
+ <constant>failed</constant>, <constant>activating</constant>, <constant>deactivating</constant>. The SUB
+ column shows the unit-type-specific detailed state of the unit, possible values vary by unit type. The list
+ of possible LOAD, ACTIVE, and SUB states is not constant and new systemd releases may both add and remove
+ values. <programlisting>systemctl --state=help</programlisting> command maybe be used to display the
+ current set of possible values.</para>
<para>This is the default command.</para>
</listitem>
</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><emphasis>NEXT</emphasis> shows the next time the timer will run.</para>
<para><emphasis>LEFT</emphasis> shows how long till the next time the timer runs.</para>
<para><emphasis>LAST</emphasis> shows the last time the timer ran.</para>
- <para><emphasis>PASSED</emphasis> shows has long as passed since the timer laset ran.</para>
+ <para><emphasis>PASSED</emphasis> shows how long has passed since the timer last ran.</para>
<para><emphasis>UNIT</emphasis> shows the name of the timer</para>
<para><emphasis>ACTIVATES</emphasis> shows the name the service the timer activates when it runs.</para>
<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
<para>The "Loaded:" line in the output will show <literal>loaded</literal> if the unit has been loaded into
memory. Other possible values for "Loaded:" include: <literal>error</literal> if there was a problem
- loading it, <literal>not-found</literal>, and <literal>masked</literal>. Along with showing the path to
- the unit file, this line will also show the enablement state. Enabled commands start at boot. See the
- full table of possible enablement states — including the definition of <literal>masked</literal> — in the
- documentation for the <command>is-enabled</command> command.
+ loading it, <literal>not-found</literal> if not unit file was found for this unit,
+ <literal>bad-setting</literal> if an essential unit file setting could not be parsed and
+ <literal>masked</literal> if the unit file has been masked. Along with showing the path to the unit file,
+ this line will also show the enablement state. Enabled commands start at boot. See the full table of
+ possible enablement states — including the definition of <literal>masked</literal> — in the documentation
+ for the <command>is-enabled</command> command.
</para>
<para>The "Active:" line shows active state. The value is usually <literal>active</literal> or
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
<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