<refsect1>
<title>Description</title>
- <para><command>systemctl</command> may be used to
- introspect and control the state of the
+ <para><command>systemctl</command> may be used to introspect and
+ control the state of the <literal>systemd</literal> system and
+ service manager. Please refer to
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
- system and service manager.</para>
+ for an introduction into the basic concepts and functionality this
+ tool manages.</para>
</refsect1>
<refsect1>
<term><option>--state=</option></term>
<listitem>
- <para>The argument should be a comma-separated list of unit LOAD,
- SUB, or ACTIVE states. When listing units, show only those
- in specified states.</para>
+ <para>The argument should be a comma-separated list of unit
+ LOAD, SUB, or ACTIVE states. When listing units, show only
+ those in specified states. Use <option>--state=failed</option>
+ to show only failed units.</para>
</listitem>
</varlistentry>
<para>If <literal>replace-irreversibly</literal> is specified,
operate like <literal>replace</literal>, but also mark the new
jobs as irreversible. This prevents future conflicting
- transactions from replacing these jobs. The jobs can still be
- cancelled using the <command>cancel</command> command.</para>
+ transactions from replacing these jobs (or even being enqueued
+ while the irreversible jobs are still pending). Irreversible
+ jobs can still be cancelled using the <command>cancel</command>
+ command.</para>
<para><literal>isolate</literal> is only valid for start
operations and causes all other units to be stopped when the
<command>snapshot</command>,
<command>is-active</command>,
<command>is-failed</command>,
+ <command>is-enabled</command>,
+ <command>is-system-running</command>,
<command>enable</command> and
<command>disable</command>.</para>
</listitem>
<xi:include href="user-system-options.xml" xpointer="user" />
<xi:include href="user-system-options.xml" xpointer="system" />
+ <!-- we do not document -failed here, as it has been made
+ redundant by -state=failed, which it predates. To keep
+ things simple we only document the new switch, while
+ keeping the old one around for compatibility only. -->
+
<varlistentry>
<term><option>--no-wall</option></term>
control processes. Note that there is only one control
process per unit at a time, as only one state change is
executed at a time. For services of type
- <varname>Type=forking</varname> the initial process started
+ <varname>Type=forking</varname>, the initial process started
by the manager for <varname>ExecStart=</varname> is a
control process, while the process ultimately forked off by
that one is then considered the main process of the unit (if
it can be determined). This is different for service units
of other types, where the process forked off by the manager
for <varname>ExecStart=</varname> is always the main process
- itself. A service unit consists of no or one main process,
- no or one control process plus any number of additional
+ itself. A service unit consists of zero or one main process,
+ zero or one control process plus any number of additional
processes. Not all unit types manage processes of these
- types however. For example for mount units control processes
+ types however. For example, for mount units, control processes
are defined (which are the invocations of
<filename>/usr/bin/mount</filename> and
<filename>/usr/bin/umount</filename>), but no main process
safe option to request an immediate reboot. If
<option>--force</option> is specified twice for these
operations, they will be executed immediately without
- terminating any processes or umounting any file
+ terminating any processes or unmounting any file
systems. Warning: specifying <option>--force</option> twice
with any of these operations might result in data
loss.</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>--preset-mode=</option></term>
+
+ <listitem>
+ <para>Takes one of <literal>full</literal> (the default),
+ <literal>enable-only</literal>,
+ <literal>disable-only</literal>. When used with the
+ <command>preset</command> or <command>preset-all</command>
+ commands, controls whether units shall be disabled and
+ enabled according to the preset rules, or only enabled, or
+ only disabled.</para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>-n</option></term>
<term><option>--lines=</option></term>
</para>
<para>See also the options <option>--show-types</option>,
- <option>--all</option>, and <option>--failed</option>.</para>
+ <option>--all</option>, and <option>--state=</option>.</para>
</listitem>
</varlistentry>
</para>
<para>See also the options <option>--all</option> and
- <option>--failed</option>.</para>
+ <option>--state=</option>.</para>
</listitem>
</varlistentry>
file.</para>
<para>This command should not be confused with the
- <command>daemon-reload</command> or <command>load</command>
- commands.</para>
+ <command>daemon-reload</command> command.</para>
</listitem>
</varlistentry>
<para>Show terse runtime status information about one or
more units, followed by most recent log data from the
journal. If no units are specified, show system status. If
- combined with <option>--all</option> also shows status of
+ combined with <option>--all</option>, also show the status of
all units (subject to limitations specified with
<option>-t</option>). If a PID is passed, show information
about the unit the process belongs to.</para>
the system, or for all future logins of all users, or only this
boot. Note that in the last case, no systemd daemon
configuration is reloaded.</para>
+
+ <para>Using <command>enable</command> on masked units
+ results in an error.</para>
</listitem>
</varlistentry>
<tbody>
<row>
<entry><literal>enabled</literal></entry>
- <entry morerows='1'>Enabled through a symlink in <filename>.wants</filename> directory (permanently or just in <filename>/run</filename>)</entry>
+ <entry morerows='1'>Enabled through a symlink in <filename>.wants</filename> directory (permanently or just in <filename>/run</filename>).</entry>
<entry morerows='1'>0</entry>
</row>
<row>
</row>
<row>
<entry><literal>linked</literal></entry>
- <entry morerows='1'>Made available through a symlink to the unit file (permanently or just in <filename>/run</filename>)</entry>
+ <entry morerows='1'>Made available through a symlink to the unit file (permanently or just in <filename>/run</filename>).</entry>
<entry morerows='1'>1</entry>
</row>
<row>
</row>
<row>
<entry><literal>masked</literal></entry>
- <entry morerows='1'>Disabled entirely (permanently or just in <filename>/run</filename>)</entry>
+ <entry morerows='1'>Disabled entirely (permanently or just in <filename>/run</filename>).</entry>
<entry morerows='1'>1</entry>
</row>
<row>
</row>
<row>
<entry><literal>static</literal></entry>
- <entry>Unit is not enabled, but has no provisions for enabling in [Install] section</entry>
+ <entry>Unit file is not enabled, and has no provisions for enabling in the <literal>[Install]</literal> section.</entry>
+ <entry>0</entry>
+ </row>
+ <row>
+ <entry><literal>indirect</literal></entry>
+ <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>
<entry>0</entry>
</row>
<row>
<entry><literal>disabled</literal></entry>
- <entry>Unit is not enabled</entry>
+ <entry>Unit file is not enabled.</entry>
<entry>1</entry>
</row>
</tbody>
command line, to the defaults configured in the preset
policy files. This has the same effect as
<command>disable</command> or <command>enable</command>,
- depending how the unit is listed in the preset files. For
- more information on the preset policy format, see
+ depending how the unit is listed in the preset files.</para>
+
+ <para>Use <option>--preset-mode=</option> to control
+ whether units shall be enabled and disabled, or only
+ enabled, or only disabled.</para>
+
+ <para>For more information on the preset policy format,
+ see
<citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
For more information on the concept of presets, please
- consult the
- <ulink url="http://freedesktop.org/wiki/Software/systemd/Preset">Preset</ulink>
+ consult the <ulink
+ url="http://freedesktop.org/wiki/Software/systemd/Preset">Preset</ulink>
document.</para>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><command>preset-all</command></term>
+
+ <listitem>
+ <para>Resets all installed unit files to the defaults
+ configured in the preset policy file (see above).</para>
+
+ <para>Use <option>--preset-mode=</option> to control
+ whether units shall be enabled and disabled, or only
+ enabled, or only disabled.</para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><command>mask <replaceable>NAME</replaceable>...</command></term>
<filename>/dev/null</filename>, making it impossible to
start them. This is a stronger version of
<command>disable</command>, since it prohibits all kinds of
- activation of the unit, including manual activation. Use
- this option with care. This honors the
+ activation of the unit, including enablement and manual
+ activation. Use this option with care. This honors the
<option>--runtime</option> option to only mask temporarily
- until the next reoobt of the system.</para>
+ until the next reboot of the system.</para>
</listitem>
</varlistentry>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><command>add-wants <replaceable>TARGET</replaceable>
+ <replaceable>NAME</replaceable>...</command></term>
+ <term><command>add-requires <replaceable>TARGET</replaceable>
+ <replaceable>NAME</replaceable>...</command></term>
+
+ <listitem>
+ <para>Adds <literal>Wants=</literal> resp. <literal>Requires=</literal>
+ dependency to the specified <replaceable>TARGET</replaceable> for
+ one or more units. </para>
+
+ <para>This command honors <option>--system</option>,
+ <option>--user</option>, <option>--runtime</option> and
+ <option>--global</option> in a similar way as
+ <command>enable</command>.</para>
+
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><command>link <replaceable>FILENAME</replaceable>...</command></term>
<para>Reload systemd manager configuration. This will reload
all unit files and recreate the entire dependency
tree. While the daemon is being reloaded, all sockets systemd
- listens on on behalf of user configuration will stay
+ listens on behalf of user configuration will stay
accessible.</para> <para>This command should not be confused
- with the <command>load</command> or
- <command>reload</command> commands.</para>
+ with the <command>reload</command> command.</para>
</listitem>
</varlistentry>
<varlistentry>
<title>System Commands</title>
<variablelist>
+ <varlistentry>
+ <term><command>is-system-running</command></term>
+
+ <listitem>
+ <para>Checks whether the system is operational. This
+ returns success when the system is fully up and running,
+ meaning not in startup, shutdown or maintenance
+ mode. Failure is returned otherwise. In addition, the
+ current state is printed in a short string to standard
+ output, see table below. Use <option>--quiet</option> to
+ suppress this output.</para>
+
+ <table>
+ <title>Manager Operational States</title>
+ <tgroup cols='2'>
+ <colspec colname='name' />
+ <colspec colname='description' />
+ <thead>
+ <row>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry><varname>initializing</varname></entry>
+ <entry><para>Early bootup, before
+ <filename>basic.target</filename> is reached
+ or the <varname>maintenance</varname> state entered.
+ </para></entry>
+ </row>
+ <row>
+ <entry><varname>starting</varname></entry>
+ <entry><para>Late bootup, before the job queue
+ becomes idle for the first time, or one of the
+ rescue targets are reached.</para></entry>
+ </row>
+ <row>
+ <entry><varname>running</varname></entry>
+ <entry><para>The system is fully
+ operational.</para></entry>
+ </row>
+ <row>
+ <entry><varname>degraded</varname></entry>
+ <entry><para>The system is operational but one or more
+ units failed.</para></entry>
+ </row>
+ <row>
+ <entry><varname>maintenance</varname></entry>
+ <entry><para>The rescue or emergency target is
+ active.</para></entry>
+ </row>
+ <row>
+ <entry><varname>stopping</varname></entry>
+ <entry><para>The manager is shutting
+ down.</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><command>default</command></term>
<command>isolate default.target</command>.</para>
</listitem>
</varlistentry>
+
<varlistentry>
<term><command>rescue</command></term>
<refsect2>
<title>Parameter Syntax</title>
- <para>Unit ommands listed above take either a single unit name
+ <para>Unit commands listed above take either a single unit name
(designated as <replaceable>NAME</replaceable>), or multiple
unit specifications (designated as
<replaceable>PATTERN</replaceable>...). In the first case, the
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.resource-management</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.special</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
- <citerefentry><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry project='man-pages'><refentrytitle>wall</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd.preset</refentrytitle><manvolnum>5</manvolnum></citerefentry>
<citerefentry><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>
</para>