Query systemd-logind Directly with org.freedesktop.login1

When a script needs session or seat data, querying org.freedesktop.login1 directly beats scraping loginctl. This guide gets you querying sessions and seats, checking inhibitors, testing whether a power action is even allowed, and toggling user lingering without guessing at object paths. Allow about 15 minutes.

The examples match the installed systemd 255 interface on this machine.

Before you start

You need a running systemd-logind service and the busctl command. Read-only queries normally need no elevated privileges. Changing lingering, seat assignments, reboot behaviour or power state is policy-controlled and may need authorisation.

systemctl --version | head -2
command -v busctl

Expect output starting systemd 255 and a path such as /usr/bin/busctl. If busctl is missing, install the systemd package through your distribution's normal process before continuing.

1. Find the manager interface

The service name is org.freedesktop.login1, its manager object is /org/freedesktop/login1. Introspection asks the live daemon what it exposes, which beats trusting a copied interface listing:

busctl introspect org.freedesktop.login1 /org/freedesktop/login1

Look for the org.freedesktop.login1.Manager interface with entries such as ListSessions, ListSeats, ListInhibitors and NCurrentSessions. The installed manpage documents the same manager object, but an upgraded daemon can expose a different set of versioned members.

2. List sessions, users and seats

The manager methods give you a compact inventory. The first call returns session ID, numeric user ID, user name, seat ID and session object path; an empty seat field is normal for a session with no attached seat.

busctl call org.freedesktop.login1 /org/freedesktop/login1 \
  org.freedesktop.login1.Manager ListSessions

busctl call org.freedesktop.login1 /org/freedesktop/login1 \
  org.freedesktop.login1.Manager ListUsers

busctl call org.freedesktop.login1 /org/freedesktop/login1 \
  org.freedesktop.login1.Manager ListSeats

Output starts with a type signature such as a(susso) for sessions, then the records. Do not assume seat0 is present just because the manpage calls it the usual default: persistent device assignments can move devices to other seats.

To inspect a specific session once you have its ID, substitute it into the path:

SESSION_ID="REPLACE_WITH_SESSION_ID"
busctl introspect org.freedesktop.login1 \
  "/org/freedesktop/login1/session/$SESSION_ID"

Object paths are data from the daemon. Keep the quotes around a shell variable, and do not build a path from an untrusted value without checking it first.

3. Inspect inhibitors before touching power

Inhibitors are why a shutdown, sleep or key action might be delayed or refused. List them before you go troubleshooting:

busctl call org.freedesktop.login1 /org/freedesktop/login1 \
  org.freedesktop.login1.Manager ListInhibitors

busctl get-property org.freedesktop.login1 /org/freedesktop/login1 \
  org.freedesktop.login1.Manager BlockInhibited

busctl get-property org.freedesktop.login1 /org/freedesktop/login1 \
  org.freedesktop.login1.Manager DelayInhibited

The list gives you what is inhibited, the owning application, its reason, the mode, user ID and process ID. The two properties are colon-separated summaries for block and delay locks. Example: an inhibitor is released when the creating process closes the file descriptor it was given, so killing that process can clear a lock as a side effect.

4. Test capability without triggering it

The Can... methods report whether an operation is unavailable, allowed, denied or needs authorisation. They do not perform the operation. Test whatever you plan to offer:

busctl call org.freedesktop.login1 /org/freedesktop/login1 \
  org.freedesktop.login1.Manager CanReboot

busctl call org.freedesktop.login1 /org/freedesktop/login1 \
  org.freedesktop.login1.Manager CanSuspend

Each result is one of na, yes, no or challenge. challenge means the operation is supported but needs authorisation. Treat yes as permission under the current policy, not a guarantee the hardware will actually complete suspend or reboot.

5. Change user lingering, then verify it

User lingering keeps a user's runtime directory alive and lets their user services keep running after logout. It is persistent state, not a session flag. Choose the numeric UID deliberately: the D-Bus method expects an unsigned integer, not a name.

This example enables lingering for UID 1000. It changes system state and may need the polkit privilege org.freedesktop.login1.set-user-linger:

USER_UID="1000"
busctl call org.freedesktop.login1 /org/freedesktop/login1 \
  org.freedesktop.login1.Manager SetUserLinger u "$USER_UID" b true b false

The final boolean controls whether polkit can interactively prompt for credentials. With false, a caller that needs a prompt fails instead of hanging. Verify through the user object:

busctl call org.freedesktop.login1 /org/freedesktop/login1 \
  org.freedesktop.login1.Manager GetUser u "$USER_UID"

USER_PATH="REPLACE_WITH_OBJECT_PATH_FROM_THE_PREVIOUS_COMMAND"
busctl get-property org.freedesktop.login1 "$USER_PATH" \
  org.freedesktop.login1.User Linger

Checkpoint: the property should now read b true. If you only enabled this to test, undo it with the same method and b false:

busctl call org.freedesktop.login1 /org/freedesktop/login1 \
  org.freedesktop.login1.Manager SetUserLinger u "$USER_UID" b false b false

Do not confuse lingering with a login session. It lets user services run without a login, but it does not create an interactive session or attach a seat.

Common traps

• Wrong bus. logind lives on the system bus. Adding --user points at a different bus and queries nothing useful.
• Wrong signature. SetUserLinger takes an unsigned UID and two booleans, so the call needs u, b, b before their values, in that order.
• Unsafe experimentation. TerminateSession, KillUser, PowerOff and related calls change or stop live work. Run the inventory and Can... methods first.
• Assumed privileges. polkit policy, other sessions and inhibitors all affect authorisation. A successful introspection query does not mean every method will succeed.
• Interface drift. This guide targets systemd 255. Re-run introspection after an upgrade and check the manpage for newly added members.