X11 Secure Hibernation

Secure your desktop session automatically when hibernating.

This repository provides two small shell scripts that work together to ensure your session is locked before hibernation or immediately on resume, depending on timing and desktop environment.

The locking method used is selected dynamically based on what is available on the system, not on which desktop environment you are running.

---

Locking behaviour (selection order)

The watchdog script selects one locking mechanism, in the following order:

1. KDE Plasma (5 or 6)

• Uses native KDE screen locking via DBus
• Works on X11 and Wayland
• No external screensaver required

This is used whenever KDE’s screensaver interface is detected as active.

---

2. xfce4-screensaver

• Used if KDE is not active and xfce4-screensaver is installed or running
• Does not require the XFCE desktop environment
• Works on X11 and Wayland
• Waits until the screensaver daemon is fully initialised before locking (race-safe)

Only the xfce4-screensaver package is required — nothing else from XFCE.

---

3. xscreensaver

• Fallback for barebones X11 environments
• Requires xscreensaver
• X11 only
• Starts the daemon if necessary, then locks once it is ready

---

Prerequisites

You need at least one of the following available:

• KDE Plasma 5 or 6 (X11 or Wayland)
• xfce4-screensaver (X11 or Wayland, no XFCE DE required)
• xscreensaver (X11 only)

---

Scripts

1. Hibernate — hibernation trigger

This script initiates hibernation safely by first creating a marker file:

/tmp/$USER-Hibernated

If the marker file cannot be created:

• A critical desktop notification is shown
• An optional email notification is sent
• Hibernation proceeds anyway (fail‑open)

This ensures hibernation is never blocked by a locking failure.

Privilege escalation

The script does not assume sudo, but does have it as the default.

You can configure the method used at the top of the script:

sudomethod="sudo"   # alternatives: kdesu, or any other su wrapper

Requirements

One of the following must be configured:

• sudo without a password
• kdesu
• another privilege escalation mechanism supported by your system

---

2. HibernateReturnScreensaverLock — session lock watchdog

This script runs continuously in the background.

It:

• Monitors /tmp/$USER-Hibernated
• Locks the session using the appropriate mechanism
• Handles startup races safely
• Deletes the marker once locking has been initiated
• Ensures only one instance of the watchdog is running

Locking may occur:

• Immediately before suspend, or
• Immediately on resume

Both cases are intentional and secure.

---

Installation

git clone https://github.com/gitdwarf/linux-secure-hibernation.git
cd linux-secure-hibernation
chmod +x Hibernate HibernateReturnScreensaverLock

Start the watchdog (recommended via session autostart):

./HibernateReturnScreensaverLock &

Use Hibernate instead of calling loginctl hibernate directly.

---

Design notes

• Marker‑file based signalling (/tmp/$USER-Hibernated)
• No systemd user services required
• No assumptions about desktop environment
• Explicit handling of screensaver initialisation races
• Minimal dependencies, plain shell scripts

---

License

MIT License — see LICENSE for details.