Manage Systemd Units

systemd exposes its manager interface on the system D-Bus bus at org.freedesktop.systemd1. The list_systemd_units shortcut tool wraps the ListUnits method and returns a markdown table you can filter with glob patterns.

Listing units

The simplest call lists every loaded unit:

“Show me all systemd services.”

list_systemd_units(bus="system")

This returns a table like:

Unit	Load	Active	Sub	Description
dbus.service	loaded	active	running	D-Bus System Message Bus
docker.service	loaded	active	running	Docker Application Container Engine
sshd.service	loaded	active	running	OpenSSH Daemon

Filtering with glob patterns

The pattern parameter accepts standard glob syntax. It matches against the unit name column.

“Which Docker-related units are loaded?”

list_systemd_units(bus="system", pattern="docker*")

“Show me all timer units.”

list_systemd_units(bus="system", pattern="*.timer")

“Are there any failed services?”

list_systemd_units(bus="system", pattern="*.service")

Claude reads the returned table and filters the Active column for “failed” entries.

User session units

systemd also manages per-user services on the session bus. Pass bus="session" to see them:

“List my user-level systemd services.”

list_systemd_units(bus="session", pattern="*.service")

This shows units managed by systemctl --user — things like Pipewire, the XDG desktop portal, and any user-installed services.

Reading unit properties

Each systemd unit has an object path under /org/freedesktop/systemd1/unit/. To get detailed properties for a specific unit, use get_all_properties on its object path.

1. Find the unit’s object path. The path encodes the unit name with underscores replacing special characters. For docker.service, the path is /org/freedesktop/systemd1/unit/docker_2eservice.

2. Read its properties. Ask Claude to read all properties on the org.freedesktop.systemd1.Unit interface:

   get_all_properties(
       bus="system",
       service="org.freedesktop.systemd1",
       object_path="/org/freedesktop/systemd1/unit/docker_2eservice",
       interface="org.freedesktop.systemd1.Unit"
   )

3. Interpret the results. The properties include ActiveState, SubState, LoadState, Description, ActiveEnterTimestamp, InactiveEnterTimestamp, MainPID, memory and CPU accounting values, and the full dependency graph (Requires, After, WantedBy).

Tip

If you are unsure of the exact object path encoding, use list_objects to walk the systemd object tree:

list_objects(bus="system", service="org.freedesktop.systemd1", root_path="/org/freedesktop/systemd1/unit")

This returns all unit object paths. The tree walk is bounded to 500 nodes and 60 seconds, which is usually enough for the unit subtree.

Inspecting the manager interface

The systemd manager itself sits at /org/freedesktop/systemd1 and exposes methods for starting, stopping, restarting, and reloading units. To see everything available:

“What methods does the systemd manager expose?”

introspect(
    bus="system",
    service="org.freedesktop.systemd1",
    object_path="/org/freedesktop/systemd1",
    interface_filter="org.freedesktop.systemd1.Manager"
)

This returns the full list of methods (StartUnit, StopUnit, RestartUnit, ReloadUnit, ListUnitFiles, and many more), properties (Version, Features, Virtualization), and signals (UnitNew, UnitRemoved, JobNew).

Calling systemd methods

Because systemd lives on the system bus, call_method triggers a confirmation prompt before execution. This protects against accidental service disruption.

“Restart the nginx service.”

call_method(
    bus="system",
    service="org.freedesktop.systemd1",
    object_path="/org/freedesktop/systemd1",
    interface="org.freedesktop.systemd1.Manager",
    method="RestartUnit",
    args='["nginx.service", "replace"]',
    signature="ss"
)

Claude presents the confirmation prompt. After you approve, systemd restarts the unit and returns the job object path.

Caution

Starting, stopping, and restarting units may also require polkit authorization depending on your system configuration. If the call fails with an authorization error, see the Lock Down Permissions guide for configuring polkit rules.

Common patterns

Find all failed services and read their status:

Ask Claude to list all .service units, identify any with Active=failed, then read their properties to see the Result, ExecMainStatus, and log output hints.

Check when a service last restarted:

Read the ActiveEnterTimestamp property on the unit’s object path. systemd reports this as a microsecond Unix timestamp.

List all enabled timers and their next trigger time:

List units matching *.timer, then for each timer read the NextElapseUSecRealtime property from the org.freedesktop.systemd1.Timer interface on the timer’s object path.