]>
<!--
+ SPDX-License-Identifier: LGPL-2.1+
+
This file is part of systemd.
Copyright 2010 Lennart Poettering
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>
+ command. This job mode should be used on any transaction which
+ pulls in <filename>shutdown.target</filename>.</para>
<para><literal>isolate</literal> is only valid for start
operations and causes all other units to be stopped when the
</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>
<xi:include href="user-system-options.xml" xpointer="user" />
<xi:include href="user-system-options.xml" xpointer="system" />
- <!-- we do not document -failed here, as it has been made
- redundant by -state=failed, which it predates. To keep
- things simple, we only document the new switch, while
- keeping the old one around for compatibility only. -->
+ <varlistentry>
+ <term><option>--failed</option></term>
+
+ <listitem>
+ <para>List units in failed state. This is equivalent to
+ <option>--state=failed</option>.</para>
+ </listitem>
+ </varlistentry>
<varlistentry>
<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>
<listitem>
<para>List timer units currently in memory, ordered by the time they elapse next. If one or more
<replaceable>PATTERN</replaceable>s are specified, only units matching one of them are shown.
+ Produces output similar to
+ <programlisting>
+NEXT LEFT LAST PASSED UNIT ACTIVATES
+n/a n/a Thu 2017-02-23 13:40:29 EST 3 days ago ureadahead-stop.timer ureadahead-stop.service
+Sun 2017-02-26 18:55:42 EST 1min 14s left Thu 2017-02-23 13:54:44 EST 3 days ago systemd-tmpfiles-clean.timer systemd-tmpfiles-clean.service
+Sun 2017-02-26 20:37:16 EST 1h 42min left Sun 2017-02-26 11:56:36 EST 6h ago apt-daily.timer apt-daily.service
+Sun 2017-02-26 20:57:49 EST 2h 3min left Sun 2017-02-26 11:56:36 EST 6h ago snapd.refresh.timer snapd.refresh.service
+ </programlisting>
</para>
+ <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>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>
+
<para>Also see <option>--all</option> and <option>--state=</option>.</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>
<term><command>isolate <replaceable>NAME</replaceable></command></term>
<listitem>
- <para>Start the unit specified on the command line and its
- dependencies and stop all others. If a unit name with no
- extension is given, an extension of
+ <para>Start the unit specified on the command line and its dependencies
+ and stop all others, unless they have
+ <option>IgnoreOnIsolate=yes</option> (see
+ <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
+ If a unit name with no extension is given, an extension of
<literal>.target</literal> will be assumed.</para>
<para>This is similar to changing the runlevel in a
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.
<programlisting>$ systemctl status bluetooth
● bluetooth.service - Bluetooth service
- Loaded: loaded (/lib/systemd/system/bluetooth.service; enabled; vendor preset: enabled)
+ Loaded: loaded (/usr/lib/systemd/system/bluetooth.service; enabled; vendor preset: enabled)
Active: active (running) since Wed 2017-01-04 13:54:04 EST; 1 weeks 0 days ago
Docs: man:bluetoothd(8)
Main PID: 930 (bluetoothd)
└─930 /usr/lib/bluetooth/bluetoothd
Jan 12 10:46:45 example.com bluetoothd[8900]: Not enough free handles to register service
-Jan 12 10:46:45 example.com.com bluetoothd[8900]: Current Time Service could not be registered
-Jan 12 10:46:45 example.com.com bluetoothd[8900]: gatt-time-server: Input/output error (5)
+Jan 12 10:46:45 example.com bluetoothd[8900]: Current Time Service could not be registered
+Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output error (5)
</programlisting>
<para>The dot ("●") uses color on supported terminals to summarize the unit state at a glance. White
<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>
<para>Depending on whether <option>--system</option>, <option>--user</option>, <option>--runtime</option>,
or <option>--global</option> is specified, this enables the unit for the system, for the calling user only,
- for only this boot of the system, or for all future logins of all users, or only this boot. Note that in
- the last case, no systemd daemon configuration is reloaded.</para>
+ for only this boot of the system, or for all future logins of all users. Note that in the last case, no
+ systemd daemon configuration is reloaded.</para>
<para>Using <command>enable</command> on masked units is not supported and results in an error.</para>
</listitem>
<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>
+ <ulink url="https://www.freedesktop.org/wiki/Software/systemd/Preset">Preset</ulink>
document.</para>
</listitem>
</varlistentry>
<tbody>
<row>
<entry><literal>enabled</literal></entry>
- <entry morerows='1'>Enabled via <filename>.wants/</filename>, <filename>.requires/</filename> or alias symlinks (permanently in <filename>/etc/systemd/system/</filename>, or transiently in <filename>/run/systemd/system/</filename>).</entry>
+ <entry morerows='1'>Enabled via <filename>.wants/</filename>, <filename>.requires/</filename> or <varname>Alias=</varname> symlinks (permanently in <filename>/etc/systemd/system/</filename>, or transiently in <filename>/run/systemd/system/</filename>).</entry>
<entry morerows='1'>0</entry>
</row>
<row>
</row>
<row>
<entry><literal>indirect</literal></entry>
- <entry>The unit file itself is not enabled, but it has a non-empty <varname>Also=</varname> setting in the <literal>[Install]</literal> unit file section, listing other unit files that might be enabled.</entry>
+ <entry>The unit file itself is not enabled, but it has a non-empty <varname>Also=</varname> setting in the <literal>[Install]</literal> unit file section, listing other unit files that might be enabled, or it has an alias under a different name through a symlink that is not specified in Also=. For template unit file, an instance different than the one specified in <varname>DefaultInstance=</varname> is enabled.</entry>
<entry>0</entry>
</row>
<row>
<term><command>show-environment</command></term>
<listitem>
- <para>Dump the systemd manager environment block. The
- environment block will be dumped in straight-forward form
- suitable for sourcing into a shell script. This environment
- block will be passed to all processes the manager
- spawns.</para>
+ <para>Dump the systemd manager environment block. This is the environment
+ block that is passed to all processes the manager spawns. The environment
+ block will be dumped in straight-forward form suitable for sourcing into
+ most shells. If no special characters or whitespace is present in the variable
+ values, no escaping is performed, and the assignments have the form
+ <literal>VARIABLE=value</literal>. If whitespace or characters which have
+ special meaning to the shell are present, dollar-single-quote escaping is
+ used, and assignments have the form <literal>VARIABLE=$'value'</literal>.
+ This syntax is known to be supported by
+ <citerefentry project='die-net'><refentrytitle>bash</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry project='die-net'><refentrytitle>zsh</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ <citerefentry project='die-net'><refentrytitle>ksh</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ and
+ <citerefentry project='die-net'><refentrytitle>busybox</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
+ <citerefentry project='die-net'><refentrytitle>ash</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+ but not
+ <citerefentry project='die-net'><refentrytitle>dash</refentrytitle><manvolnum>1</manvolnum></citerefentry>
+ or
+ <citerefentry project='die-net'><refentrytitle>fish</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+ </para>
</listitem>
</varlistentry>
<varlistentry>
<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>
projects / thirdparty / systemd.git / blobdiff