<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>
<para>The following options are understood:</para>
<variablelist>
- <varlistentry>
- <term><option>-h</option></term>
- <term><option>--help</option></term>
-
- <listitem><para>Prints a short help
- text and exits.</para></listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--version</option></term>
-
- <listitem>
- <para>Prints a short version string and exits.</para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><option>-t</option></term>
<term><option>--type=</option></term>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>-r</option></term>
+ <term><option>--recursive</option></term>
+
+ <listitem>
+ <para>When listing units, also show units of local
+ containers. Units of local containers will be prefixed with
+ the container name, separated by a single colon character
+ (<literal>:</literal>).</para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>--reverse</option></term>
<varlistentry>
<term><option>--after</option></term>
+
+ <listitem>
+ <para>With <command>list-dependencies</command>, show the
+ units that are ordered before the specified unit. In other
+ words, list the units that are in the <varname>After=</varname>
+ directive of the specified unit, have the specified unit in
+ their <varname>Before=</varname> directive, or are otherwise
+ implicit dependencies of the specified unit.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
<term><option>--before</option></term>
<listitem>
- <para>Show which units are started after or before
- with <command>list-dependencies</command>, respectively.
- </para>
+ <para>With <command>list-dependencies</command>, show the
+ units that are ordered after the specified unit. In other
+ words, list the units that are in the <varname>Before=</varname>
+ directive of the specified unit, have the specified unit in
+ their <varname>After=</varname> directive, or otherwise depend
+ on the specified unit.</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>
</listitem>
</varlistentry>
- <varlistentry>
- <term><option>--no-pager</option></term>
-
- <listitem>
- <para>Do not pipe output into a pager.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--system</option></term>
-
- <listitem>
- <para>Talk to the systemd system manager. (Default)</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><option>--user</option></term>
-
- <listitem>
- <para>Talk to the systemd manager of the calling
- user.</para>
- </listitem>
- </varlistentry>
+ <xi:include href="user-system-options.xml" xpointer="user" />
+ <xi:include href="user-system-options.xml" xpointer="system" />
<varlistentry>
<term><option>--no-wall</option></term>
<listitem>
<para>When used with <command>kill</command>, choose which
- processes to kill. Must be one of <option>main</option>,
- <option>control</option> or <option>all</option> to select
- whether to kill only the main process of the unit, the
- control process or all processes of the unit. If omitted,
- defaults to <option>all</option>.</para>
+ processes to send a signal to. Must be one of
+ <option>main</option>, <option>control</option> or
+ <option>all</option> to select whether to kill only the main
+ process, the control process or all processes of the
+ unit. The main process of the unit is the one that defines
+ the life-time of it. A control process of a unit is one that
+ is invoked by the manager to induce state changes of it. For
+ example, all processes started due to the
+ <varname>ExecStartPre=</varname>,
+ <varname>ExecStop=</varname> or
+ <varname>ExecReload=</varname> settings of service units are
+ 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
+ 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 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
+ are defined (which are the invocations of
+ <filename>/usr/bin/mount</filename> and
+ <filename>/usr/bin/umount</filename>), but no main process
+ is defined. If omitted, defaults to
+ <option>all</option>.</para>
</listitem>
</varlistentry>
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>
</varlistentry>
<varlistentry>
- <term><option>-H</option></term>
- <term><option>--host</option></term>
+ <term><option>--preset-mode=</option></term>
<listitem>
- <para>Execute the operation remotely. Specify a hostname, or
- username and hostname separated by <literal>@</literal>, to
- connect to. This will use SSH to talk to the remote systemd
- instance.</para>
+ <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>-M</option></term>
- <term><option>--machine=</option></term>
-
- <listitem><para>Execute the operation on a local
- container. Specify a container name to connect
- to.</para></listitem>
- </varlistentry>
-
<varlistentry>
<term><option>-n</option></term>
<term><option>--lines=</option></term>
</listitem>
</varlistentry>
+ <xi:include href="user-system-options.xml" xpointer="host" />
+ <xi:include href="user-system-options.xml" xpointer="machine" />
+
+ <xi:include href="standard-options.xml" xpointer="help" />
+ <xi:include href="standard-options.xml" xpointer="version" />
+ <xi:include href="standard-options.xml" xpointer="no-pager" />
</variablelist>
</refsect1>
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>
<listitem>
<para>Send a signal to one or more processes of the
unit. Use <option>--kill-who=</option> to select which
- process to kill. Use <option>--kill-mode=</option> to select
- the kill mode and <option>--signal=</option> to select the
- signal to send.</para>
+ process to kill. Use <option>--signal=</option> to select
+ the signal to send.</para>
</listitem>
</varlistentry>
<varlistentry>
<listitem>
<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 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>
+ journal. If no units are specified, show system status. If
+ 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>
<para>This function is intended to generate human-readable
output. If you are looking for computer-parsable output,
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>
activation of the unit, including 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>
</variablelist>
</refsect2>
+ <refsect2>
+ <title>Machine Commands</title>
+
+ <variablelist>
+ <varlistentry>
+ <term><command>list-machines <optional><replaceable>PATTERN</replaceable>...</optional></command></term>
+
+ <listitem>
+ <para>List the host and all running local containers with
+ their state. If one or more
+ <replaceable>PATTERN</replaceable>s are specified, only
+ containers matching one of them are shown.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect2>
+
<refsect2>
<title>Job Commands</title>
<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 running. 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. Use
+ <option>--quiet</option> to suppress output of this state
+ string.</para>
+ </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
<literal>[]</literal> may be used. See
<citerefentry><refentrytitle>glob</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for more details. The patterns are matched against the names of
- currently loaded units, and patterns which don't match anything
+ currently loaded units, and patterns which do not match anything
are silently skipped. For example:
<programlisting># systemctl stop sshd@*.service</programlisting>
will stop all <filename>sshd@.service</filename> instances.
<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>