]>
<!--
+ 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><option>--no-wall</option></term>
<listitem>
- <para>Do not send wall message before halt, power-off,
- reboot.</para>
+ <para>Do not send wall message before halt, power-off and reboot.</para>
</listitem>
</varlistentry>
<option>--force</option> twice with any of these operations might result in data loss. Note that when
<option>--force</option> is specified twice the selected operation is executed by
<command>systemctl</command> itself, and the system manager is not contacted. This means the command should
- succeed even when the system manager hangs or crashed.</para>
+ succeed even when the system manager has crashed.</para>
</listitem>
</varlistentry>
<term><option>--message=</option></term>
<listitem>
- <para>When used with <command>halt</command>,
- <command>poweroff</command>, <command>reboot</command> or
- <command>kexec</command>, set a short message explaining the reason
- for the operation. The message will be logged together with the
- default shutdown message.</para>
+ <para>When used with <command>halt</command>, <command>poweroff</command> or <command>reboot</command>, set a
+ short message explaining the reason for the operation. The message will be logged together with the default
+ shutdown message.</para>
</listitem>
</varlistentry>
<term><command>restart <replaceable>PATTERN</replaceable>…</command></term>
<listitem>
- <para>Stop and then start one or more units specified on the
- command line. If the units are not running yet, they will
- be started.</para>
+ <para>Stop and then start one or more units specified on the command line. If the units are not running
+ yet, they will be started.</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
+ <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
+ restart operation an explicit <command>systemctl stop</command> command followed by <command>systemctl
+ start</command> should be issued.</para>
</listitem>
</varlistentry>
<varlistentry>
<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
<term><command>default</command></term>
<listitem>
- <para>Enter default mode. This is mostly equivalent to
- <command>isolate default.target</command>.</para>
+ <para>Enter default mode. This is equivalent to <command>systemctl isolate default.target</command>. This
+ operation is blocking by default, use <option>--no-block</option> to request asynchronous behavior.</para>
</listitem>
</varlistentry>
<term><command>rescue</command></term>
<listitem>
- <para>Enter rescue mode. This is mostly equivalent to
- <command>isolate rescue.target</command>, but also prints a
- wall message to all users.</para>
+ <para>Enter rescue mode. This is equivalent to <command>systemctl isolate rescue.target</command>. This
+ operation is blocking by default, use <option>--no-block</option> to request asynchronous behavior.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>emergency</command></term>
<listitem>
- <para>Enter emergency mode. This is mostly equivalent to
- <command>isolate emergency.target</command>, but also prints
- a wall message to all users.</para>
+ <para>Enter emergency mode. This is equivalent to <command>systemctl isolate
+ emergency.target</command>. This operation is blocking by default, use <option>--no-block</option> to
+ request asynchronous behavior.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>halt</command></term>
<listitem>
- <para>Shut down and halt the system. This is mostly equivalent to <command>start halt.target
- --job-mode=replace-irreversibly</command>, but also prints a wall message to all users. If combined with
- <option>--force</option>, shutdown of all running services is skipped, however all processes are killed and
- all file systems are unmounted or mounted read-only, immediately followed by the system halt. If
- <option>--force</option> is specified twice, the operation is immediately executed without terminating any
- processes or unmounting any file systems. This may result in data loss. Note that when
- <option>--force</option> is specified twice the halt operation is executed by
- <command>systemctl</command> itself, and the system manager is not contacted. This means the command should
- succeed even when the system manager hangs or crashed.</para>
+ <para>Shut down and halt the system. This is mostly equivalent to <command>systemctl start halt.target
+ --job-mode=replace-irreversibly --no-block</command>, but also prints a wall message to all users. This command is
+ asynchronous; it will return after the halt operation is enqueued, without waiting for it to complete. Note
+ that this operation will simply halt the OS kernel after shutting down, leaving the hardware powered
+ on. Use <command>systemctl poweroff</command> for powering off the system (see below).</para>
+
+ <para>If combined with <option>--force</option>, shutdown of all running services is skipped, however all
+ processes are killed and all file systems are unmounted or mounted read-only, immediately followed by the
+ system halt. If <option>--force</option> is specified twice, the operation is immediately executed without
+ terminating any processes or unmounting any file systems. This may result in data loss. Note that when
+ <option>--force</option> is specified twice the halt operation is executed by <command>systemctl</command>
+ itself, and the system manager is not contacted. This means the command should succeed even when the system
+ manager has crashed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>poweroff</command></term>
<listitem>
- <para>Shut down and power-off the system. This is mostly equivalent to <command>start poweroff.target
- --job-mode=replace-irreversibly</command>, but also prints a wall message to all users. If combined with
- <option>--force</option>, shutdown of all running services is skipped, however all processes are killed and
- all file systems are unmounted or mounted read-only, immediately followed by the powering off. If
- <option>--force</option> is specified twice, the operation is immediately executed without terminating any
- processes or unmounting any file systems. This may result in data loss. Note that when
+ <para>Shut down and power-off the system. This is mostly equivalent to <command>systemctl start
+ poweroff.target --job-mode=replace-irreversibly --no-block</command>, but also prints a wall message to all
+ users. This command is asynchronous; it will return after the power-off operation is enqueued, without
+ waiting for it to complete.</para>
+
+ <para>If combined with <option>--force</option>, shutdown of all running services is skipped, however all
+ processes are killed and all file systems are unmounted or mounted read-only, immediately followed by the
+ powering off. If <option>--force</option> is specified twice, the operation is immediately executed without
+ terminating any processes or unmounting any file systems. This may result in data loss. Note that when
<option>--force</option> is specified twice the power-off operation is executed by
<command>systemctl</command> itself, and the system manager is not contacted. This means the command should
- succeed even when the system manager hangs or crashed.</para>
+ succeed even when the system manager has crashed.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><command>reboot <optional><replaceable>arg</replaceable></optional></command></term>
<listitem>
- <para>Shut down and reboot the system. This is mostly equivalent to <command>start reboot.target
- --job-mode=replace-irreversibly</command>, but also prints a wall message to all users. If combined with
- <option>--force</option>, shutdown of all running services is skipped, however all processes are killed and
- all file systems are unmounted or mounted read-only, immediately followed by the reboot. If
- <option>--force</option> is specified twice, the operation is immediately executed without terminating any
- processes or unmounting any file systems. This may result in data loss. Note that when
+ <para>Shut down and reboot the system. This is mostly equivalent to <command>systemctl start reboot.target
+ --job-mode=replace-irreversibly --no-block</command>, but also prints a wall message to all users. This
+ command is asynchronous; it will return after the reboot operation is enqueued, without waiting for it to
+ complete.</para>
+
+ <para>If combined with <option>--force</option>, shutdown of all running services is skipped, however all
+ processes are killed and all file systems are unmounted or mounted read-only, immediately followed by the
+ reboot. If <option>--force</option> is specified twice, the operation is immediately executed without
+ terminating any processes or unmounting any file systems. This may result in data loss. Note that when
<option>--force</option> is specified twice the reboot operation is executed by
<command>systemctl</command> itself, and the system manager is not contacted. This means the command should
- succeed even when the system manager hangs or crashed.</para>
-
- <para>If the optional argument
- <replaceable>arg</replaceable> is given, it will be passed
- as the optional argument to the
- <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
- system call. The value is architecture and firmware
- specific. As an example, <literal>recovery</literal> might
- be used to trigger system recovery, and
- <literal>fota</literal> might be used to trigger a
+ succeed even when the system manager has crashed.</para>
+
+ <para>If the optional argument <replaceable>arg</replaceable> is given, it will be passed as the optional
+ argument to the <citerefentry><refentrytitle>reboot</refentrytitle><manvolnum>2</manvolnum></citerefentry>
+ system call. The value is architecture and firmware specific. As an example, <literal>recovery</literal>
+ might be used to trigger system recovery, and <literal>fota</literal> might be used to trigger a
<quote>firmware over the air</quote> update.</para>
</listitem>
</varlistentry>
<term><command>kexec</command></term>
<listitem>
- <para>Shut down and reboot the system via kexec. This is
- mostly equivalent to <command>start kexec.target --job-mode=replace-irreversibly</command>,
- but also prints a wall message to all users. If combined
- with <option>--force</option>, shutdown of all running
- services is skipped, however all processes are killed and
- all file systems are unmounted or mounted read-only,
- immediately followed by the reboot.</para>
+ <para>Shut down and reboot the system via <command>kexec</command>. This is equivalent to
+ <command>systemctl start kexec.target --job-mode=replace-irreversibly --no-block</command>. This command is
+ asynchronous; it will return after the reboot operation is enqueued, without waiting for it to
+ complete.</para>
+
+ <para>If combined with <option>--force</option>, shutdown of all running services is skipped, however all
+ processes are killed and all file systems are unmounted or mounted read-only, immediately followed by the
+ reboot.</para>
</listitem>
</varlistentry>
<term><command>exit <optional><replaceable>EXIT_CODE</replaceable></optional></command></term>
<listitem>
- <para>Ask the systemd manager to quit. This is only
- supported for user service managers (i.e. in conjunction
- with the <option>--user</option> option) or in containers
- and is equivalent to <command>poweroff</command> otherwise.</para>
-
- <para>The systemd manager can exit with a non-zero exit
- code if the optional argument
- <replaceable>EXIT_CODE</replaceable> is given.</para>
+ <para>Ask the service manager to quit. This is only supported for user service managers (i.e. in
+ conjunction with the <option>--user</option> option) or in containers and is equivalent to
+ <command>poweroff</command> otherwise. This command is asynchronous; it will return after the exit
+ operation is enqueued, without waiting for it to complete.</para>
+
+ <para>The service manager will exit with the specified exit code, if
+ <replaceable>EXIT_CODE</replaceable> is passed.</para>
</listitem>
</varlistentry>
<term><command>suspend</command></term>
<listitem>
- <para>Suspend the system. This will trigger activation of
- the special <filename>suspend.target</filename> target.
- </para>
+ <para>Suspend the system. This will trigger activation of the special target unit
+ <filename>suspend.target</filename>. This command is asynchronous, and will return after the suspend
+ operation is successfully enqueued. It will not wait for the suspend/resume cycle to complete.</para>
</listitem>
</varlistentry>
<term><command>hibernate</command></term>
<listitem>
- <para>Hibernate the system. This will trigger activation of
- the special <filename>hibernate.target</filename> target.
- </para>
+ <para>Hibernate the system. This will trigger activation of the special target unit
+ <filename>hibernate.target</filename>. This command is asynchronous, and will return after the hibernation
+ operation is successfully enqueued. It will not wait for the hibernate/thaw cycle to complete.</para>
</listitem>
</varlistentry>
<term><command>hybrid-sleep</command></term>
<listitem>
- <para>Hibernate and suspend the system. This will trigger
- activation of the special
- <filename>hybrid-sleep.target</filename> target.</para>
+ <para>Hibernate and suspend the system. This will trigger activation of the special target unit
+ <filename>hybrid-sleep.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 cycle to complete.</para>
</listitem>
</varlistentry>
</variablelist>
<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
projects / thirdparty / systemd.git / blobdiff