systemd-inhibit explained: keeping long Linux jobs alive through suspend and reboot

The problem

A multi-hour rsync stalls because the laptop suspended. A reboot lands while a distribution upgrade is unpacking. A headless box configured with IdleAction=suspend decides mid-backup that every session is idle. A guide on dev.to argues these are not application bugs: they are long-running jobs that never took an inhibitor lock, the mechanism systemd-logind exposes for temporarily holding off sleep, shutdown, idle handling and key events.

How the lock works

The underlying API is a single D-Bus call to logind, Inhibit(what, who, why, mode), which returns an open file descriptor. The lock's lifetime is tied to that descriptor: when the process holding it exits, the kernel closes the file and the lock disappears. According to the dev.to guide, this design rules out a stale-lock database or a forgotten unlock — crashed jobs drop their inhibitors automatically.

systemd-inhibit is a thin command-line wrapper over that call. It acquires the lock, execs your command, and holds the descriptor until the command finishes, so you can shield almost any job without modifying it.

What you can inhibit

Three high-level lock types cover the common failure modes:

• shutdown blocks power-off, reboot, halt and kexec requests that go through logind
• sleep covers suspend, hibernate and the hybrid variants
• idle gates automatic idle handling such as the IdleAction= path

Omit --what and you get all three at once (idle:sleep:shutdown), which the guide considers the right default whenever a job must not be interrupted.

A second family — handle-power-key, handle-suspend-key, handle-lid-switch and siblings — only turns off logind's built-in handling so a desktop environment can take over. These will not stop someone typing systemctl suspend in a root shell. The guide also flags a laptop-specific quirk: LidSwitchIgnoreInhibited= defaults to yes in logind.conf, so a high-level sleep block alone may not prevent lid-triggered suspend unless the setting is changed or the low-level lid lock is taken.

Choosing a mode

block, the default, makes the operation fail until the lock is released, though privileged users can still override it. delay lets the operation wait at most InhibitDelayMaxSec= (five seconds by default) before proceeding anyway, and applies only to sleep and shutdown — it exists for state-flushing hooks such as locking the screen before suspend, not for protecting an hours-long backup. block-weak behaves like block but is silently bypassed by root and by the lock owner's own requests. The dev.to author is explicit that inhibitors are a cooperative protocol with escape hatches for administrators, not a security boundary against root.

Practical patterns

Inspect current holders with systemd-inhibit --list (newer builds accept --), or query logind directly over D-Bus with busctl; the BlockInhibited and DelayInhibited properties expose a colon-joined union of active lock types, which the guide suggests for monitoring probes.

The basic pattern wraps the job directly:

systemd-inhibit --what=idle:sleep:shutdown
--who=backup --why="Nightly rsync of /srv" --mode=block
rsync -aHAX /srv/ /mnt/backup/srv/

The guide also recommends narrowing the lock when possible: a database dump might take only shutdown:idle, while writing a disk image — where suspend is the real enemy — takes sleep:idle. Holding the widest lock indefinitely is how laptops never sleep and batteries drain. For overnight work, the durable pattern is a oneshot service whose ExecStart= invokes systemd-inhibit around the backup script, with descriptive --who and --why labels that surface in --list output and desktop dialogs, driven by a timer.

Why it matters

Idle and sleep policy is tuned for interactive laptops, while backups, migrations and upgrades are batch work that outlives a coffee break. Inhibitor locks are the sanctioned way to reconcile the two, and they fail safely: a crashed job releases its lock because the kernel closes the descriptor. They are not a substitute for backups, fencing or package-manager locks — as the guide notes, they only postpone logind's own sleep, idle and shutdown actions — but that is exactly what a suspending laptop needs to stop killing your work mid-job.