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>
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>
</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
non-zero otherwise. Unless <option>--quiet</option> is
specified, this will also print the current unit state to
standard output.</para>
-
- <para>Unlike <command>status</command> or <command>show</command> commands, this does not
- load units. So, when a specified unit is an alias of another unit and is not loaded,
- then this outputs "inactive", even if the aliased unit is active.</para>
</listitem>
</varlistentry>
<varlistentry>
non-zero otherwise. Unless <option>--quiet</option> is
specified, this will also print the current unit state to
standard output.</para>
-
- <para>Unlike <command>status</command> or <command>show</command> commands, this does not
- load units. So, when a specified unit is an alias of another unit and is not loaded,
- then this outputs "inactive", even if the aliased unit is failed.</para>
</listitem>
</varlistentry>
<varlistentry>
are always exposed as properties ending in the <literal>…USec</literal> suffix even if a matching
configuration options end in <literal>…Sec</literal>, because microseconds is the normalized time unit used
by the system and service manager.</para>
-
- <para>As similar to <command>status</command> command, systemd implicitly loads units as necessary.
- See also <command>status</command> command for the detail.</para>
</listitem>
</varlistentry>
<varlistentry>
</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>
<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