]>
<!--
+ 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"
<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>
that are shown are additionally filtered by <option>--type=</option> and <option>--state=</option> if those
options are specified.</para>
+ <para>Produces output similar to
+ <programlisting> UNIT LOAD ACTIVE SUB DESCRIPTION
+ sys-module-fuse.device loaded active plugged /sys/module/fuse
+ -.mount loaded active mounted Root Mount
+ 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
+…
+ systemd-tmpfiles-clean.timer loaded active waiting Daily Cleanup of Temporary Directories
+
+LOAD = Reflects whether the unit definition was properly loaded.
+ACTIVE = The high-level unit activation state, i.e. generalization of SUB.
+SUB = The low-level unit activation state, values depend on unit type.
+
+123 loaded units listed. Pass --all to see loaded but inactive units, too.
+To show all installed unit files use 'systemctl list-unit-files'.
+ </programlisting>
+ The header and the last unit of a given type are underlined if the
+ 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>This is the default command.</para>
</listitem>
</varlistentry>
<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>
<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
<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 the specified exit code, if
+ <para>The service manager will exit with the specified exit code, if
<replaceable>EXIT_CODE</replaceable> is passed.</para>
</listitem>
</varlistentry>
<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