]>
<!--
+ SPDX-License-Identifier: LGPL-2.1+
+
This file is part of systemd.
Copyright 2010 Lennart Poettering
<command>systemctl</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
<arg choice="plain">COMMAND</arg>
- <arg choice="opt" rep="repeat">NAME</arg>
+ <arg choice="opt" rep="repeat">UNIT</arg>
</cmdsynopsis>
</refsynopsisdiv>
</listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>--dry-run</option></term>
+
+ <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>default</command>, <command>rescue</command>,
+ <command>emergency</command>, and <command>exit</command>.</para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term><option>-q</option></term>
<term><option>--quiet</option></term>
<term><command>reload-or-restart <replaceable>PATTERN</replaceable>…</command></term>
<listitem>
- <para>Reload one or more units if they support it. If not,
- restart them instead. If the units are not running yet, they
- will be started.</para>
+ <para>Reload one or more units if they support it. If not, stop and then start them instead. If the units
+ are not running yet, they will be started.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>try-reload-or-restart <replaceable>PATTERN</replaceable>…</command></term>
<listitem>
- <para>Reload one or more units if they support it. If not,
- restart them instead. This does nothing if the units are not
- running.</para>
+ <para>Reload one or more units if they support it. If not, stop and then start them instead. This does
+ nothing if the units are not running.</para>
<!-- Note that we don't document force-reload here, as that is just compatibility support, and we generally
don't document that. -->
</listitem>
</varlistentry>
<varlistentry>
- <term><command>isolate <replaceable>NAME</replaceable></command></term>
+ <term><command>isolate <replaceable>UNIT</replaceable></command></term>
<listitem>
<para>Start the unit specified on the command line and its dependencies
convenient.
</para>
- <para>Systemd implicitly loads units as necessary, so just running the <command>status</command> will
+ <para>systemd implicitly loads units as necessary, so just running the <command>status</command> will
attempt to load a file. The command is thus not useful for determining if something was already loaded or
not. The units may possibly also be quickly unloaded after the operation is completed if there's no reason
to keep it in memory thereafter.
</listitem>
</varlistentry>
<varlistentry>
- <term><command>set-property <replaceable>NAME</replaceable> <replaceable>ASSIGNMENT</replaceable>…</command></term>
+ <term><command>set-property <replaceable>UNIT</replaceable> <replaceable>PROPERTY</replaceable>=<replaceable>VALUE</replaceable>…</command></term>
<listitem>
<para>Set the specified unit properties at runtime where
runtime. Not all properties may be changed at runtime, but
many resource control settings (primarily those in
<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>)
- may. The changes are applied instantly, and stored on disk
+ may. The changes are applied immediately, and stored on disk
for future boots, unless <option>--runtime</option> is
passed, in which case the settings only apply until the
next reboot. The syntax of the property assignment follows
<para>Note that this command allows changing multiple
properties at the same time, which is preferable over
- setting them individually. Like unit file configuration
- settings, assigning the empty list to list parameters will
- reset the list.</para>
+ setting them individually. Like with unit file configuration
+ settings, assigning an empty list will reset the property.
+ </para>
</listitem>
</varlistentry>
<term><command>reset-failed [<replaceable>PATTERN</replaceable>…]</command></term>
<listitem>
- <para>Reset the <literal>failed</literal> state of the
- specified units, or if no unit name is passed, reset the state of all
- units. When a unit fails in some way (i.e. process exiting
- with non-zero error code, 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 restarted or reset with this command.</para>
+ <para>Reset the <literal>failed</literal> state of the specified units, or if no unit name is passed, reset
+ the state of all units. When a unit fails in some way (i.e. process exiting with non-zero error code,
+ 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>
</listitem>
</varlistentry>
<varlistentry>
<term>
<command>list-dependencies</command>
- <optional><replaceable>NAME</replaceable></optional>
+ <optional><replaceable>UNIT</replaceable></optional>
</term>
<listitem>
</varlistentry>
<varlistentry>
- <term><command>enable <replaceable>NAME</replaceable>…</command></term>
+ <term><command>enable <replaceable>UNIT</replaceable>…</command></term>
<term><command>enable <replaceable>PATH</replaceable>…</command></term>
<listitem>
automatically searched for unit files with appropriate names), or absolute paths to unit files (in which
case these files are read directly). If a specified unit file is located outside of the usual unit file
directories, an additional symlink is created, linking it into the unit configuration path, thus ensuring
- it is found when requested by commands such as <command>start</command>.</para>
+ it is found when requested by commands such as <command>start</command>. The file system where the linked
+ unit files are located must be accessible when systemd is started (e.g. anything underneath
+ <filename>/home</filename> or <filename>/var</filename> is not allowed, unless those directories are
+ located on the root file system).</para>
<para>This command will print the file system operations executed. This output may be suppressed by passing
<option>--quiet</option>.
</varlistentry>
<varlistentry>
- <term><command>disable <replaceable>NAME</replaceable>…</command></term>
+ <term><command>disable <replaceable>UNIT</replaceable>…</command></term>
<listitem>
<para>Disables one or more units. This removes all symlinks to the unit files backing the specified units
</varlistentry>
<varlistentry>
- <term><command>reenable <replaceable>NAME</replaceable>…</command></term>
+ <term><command>reenable <replaceable>UNIT</replaceable>…</command></term>
<listitem>
<para>Reenable one or more units, as specified on the command line. This is a combination of
</varlistentry>
<varlistentry>
- <term><command>preset <replaceable>NAME</replaceable>…</command></term>
+ <term><command>preset <replaceable>UNIT</replaceable>…</command></term>
<listitem>
<para>Reset the enable/disable status one or more unit files, as specified on
enabled and disabled, or only enabled, or only disabled.</para>
<para>If the unit carries no install information, it will be silently ignored
- by this command. <replaceable>NAME</replaceable> must be the real unit name,
+ by this command. <replaceable>UNIT</replaceable> must be the real unit name,
any alias names are ignored silently.</para>
<para>For more information on the preset policy format, see
</varlistentry>
<varlistentry>
- <term><command>is-enabled <replaceable>NAME</replaceable>…</command></term>
+ <term><command>is-enabled <replaceable>UNIT</replaceable>…</command></term>
<listitem>
<para>Checks whether any of the specified unit files are
</varlistentry>
<varlistentry>
- <term><command>mask <replaceable>NAME</replaceable>…</command></term>
+ <term><command>mask <replaceable>UNIT</replaceable>…</command></term>
<listitem>
<para>Mask one or more units, as specified on the command line. This will link these unit files to
</varlistentry>
<varlistentry>
- <term><command>unmask <replaceable>NAME</replaceable>…</command></term>
+ <term><command>unmask <replaceable>UNIT</replaceable>…</command></term>
<listitem>
<para>Unmask one or more unit files, as specified on the command line. This will undo the effect of
<para>Link a unit file that is not in the unit file search paths into the unit file search path. This
command expects an absolute path to a unit file. The effect of this may be undone with
<command>disable</command>. The effect of this command is that a unit file is made available for commands
- such as <command>start</command>, even though it is not installed directly in the unit search path.</para>
+ such as <command>start</command>, even though it is not installed directly in the unit search path. The
+ file system where the linked unit files are located must be accessible when systemd is started
+ (e.g. anything underneath <filename>/home</filename> or <filename>/var</filename> is not allowed, unless
+ those directories are located on the root file system).</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><command>revert <replaceable>NAME</replaceable>…</command></term>
+ <term><command>revert <replaceable>UNIT</replaceable>…</command></term>
<listitem>
<para>Revert one or more unit files to their vendor versions. This command removes drop-in configuration
<varlistentry>
<term><command>add-wants <replaceable>TARGET</replaceable>
- <replaceable>NAME</replaceable>…</command></term>
+ <replaceable>UNIT</replaceable>…</command></term>
<term><command>add-requires <replaceable>TARGET</replaceable>
- <replaceable>NAME</replaceable>…</command></term>
+ <replaceable>UNIT</replaceable>…</command></term>
<listitem>
<para>Adds <literal>Wants=</literal> or <literal>Requires=</literal>
</varlistentry>
<varlistentry>
- <term><command>edit <replaceable>NAME</replaceable>…</command></term>
+ <term><command>edit <replaceable>UNIT</replaceable>…</command></term>
<listitem>
<para>Edit a drop-in snippet or a whole replacement file if
</varlistentry>
<varlistentry>
- <term><command>set-default <replaceable>NAME</replaceable></command></term>
+ <term><command>set-default <replaceable>TARGET</replaceable></command></term>
<listitem>
<para>Set the default target to boot into. This sets
<refsect2>
<title>Parameter Syntax</title>
- <para>Unit commands listed above take either a single unit name (designated as <replaceable>NAME</replaceable>),
+ <para>Unit commands listed above take either a single unit name (designated as <replaceable>UNIT</replaceable>),
or multiple unit specifications (designated as <replaceable>PATTERN</replaceable>…). In the first case, the
unit name with or without a suffix must be given. If the suffix is not specified (unit name is "abbreviated"),
systemctl will append a suitable suffix, <literal>.service</literal> by default, and a type-specific suffix in
in memory are not considered for glob expansion.
</para>
- <para>For unit file commands, the specified <replaceable>NAME</replaceable> should be the name of the unit file
+ <para>For unit file commands, the specified <replaceable>UNIT</replaceable> should be the name of the unit file
(possibly abbreviated, see above), or the absolute path to the unit file:
<programlisting># systemctl enable foo.service</programlisting>
or