From ab8864ebc3ac01288729b44f0d5f18fff37defb5 Mon Sep 17 00:00:00 2001 From: Mark Stosberg Date: Wed, 21 Dec 2016 14:55:04 -0500 Subject: [PATCH] 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 ) --- man/systemctl.xml | 50 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/man/systemctl.xml b/man/systemctl.xml index 1440d71925..391e5dfe9c 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -876,6 +876,56 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service a similar filter for messages and might be more convenient. + + Systemd implicitly loads units as necessary, so just running the status 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. + + + + Example output from systemctl status + + $ 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) + + + The dot ("●") uses color on supported terminals to summarize the unit state at a glance. White + indicates an inactive or deactivating state. Red indicates a + failed or error state and green indicates an + active, reloading or activating state. + + + The "Loaded:" line in the output will show loaded if the unit has been loaded into + memory. Other possible values for "Loaded:" include: error if there was a problem + loading it, not-found, and masked. 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 masked — in the + documentation for the is-enabled command. + + + The "Active:" line shows active state. The value is usually active or + inactive. 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 activating or + deactivating. A special failed 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. + +