man: provide a basic guide to the `systemctl status` output (#4950)

- Show example of all `systemctl status` output and documents what possible
   "Loaded:", "Active" and "Enabled" values mean.

 - Documents what different colors of the dot mean.

 - Documents "gotcha" with load-on-demand behavior which will report units as
   "loaded" even if they are only loaded to show their status.
   (From @poettering: https://github.com/systemd/systemd/issues/5063#issuecomment-272115024 )
This commit is contained in:
Mark Stosberg 2016-12-21 14:55:04 -05:00 committed by Zbigniew Jędrzejewski-Szmek
parent e843b04ee9
commit ab8864ebc3
1 changed files with 50 additions and 0 deletions

View File

@ -876,6 +876,56 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service
a similar filter for messages and might be more
convenient.
</para>
<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.
</para>
<example>
<title>Example output from systemctl status </title>
<programlisting>$ systemctl status bluetooth
● bluetooth.service - Bluetooth service
Loaded: loaded (/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)
Status: "Running"
Tasks: 1
Memory: 648.0K
CPU: 435ms
CGroup: /system.slice/bluetooth.service
└─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)
</programlisting>
<para>The dot ("●") uses color on supported terminals to summarize the unit state at a glance. White
indicates an <literal>inactive</literal> or <literal>deactivating</literal> state. Red indicates a
<literal>failed</literal> or <literal>error</literal> state and green indicates an
<literal>active</literal>, <literal>reloading</literal> or <literal>activating</literal> state.
</para>
<para>The "Loaded:" line in the output will show <literal>loaded</literal> if the unit has been loaded into
memory. Other possible values for "Loaded:" include: <literal>error</literal> if there was a problem
loading it, <literal>not-found</literal>, and <literal>masked</literal>. Along with showing the path to
the unit file, this line will also show the enablement state. Enabled commands start at boot. See the
full table of possible enablement states — including the definition of <literal>masked</literal> — in the
documentation for the <command>is-enabled</command> command.
</para>
<para>The "Active:" line shows active state. The value is usually <literal>active</literal> or
<literal>inactive</literal>. Active could mean started, bound, plugged in, etc depending on the unit type.
The unit could also be in process of changing states, reporting a state of <literal>activating</literal> or
<literal>deactivating</literal>. A special <literal>failed</literal> state is entered when the service
failed in some way, such as a crash, exiting with an error code or timing out. If the failed state is
entered the cause will be logged for later reference.</para>
</example>
</listitem>
</varlistentry>
<varlistentry>