Python script that unlocks LUKS at boot by sending the passphrase via SSH to dropbear-initramfs.
A remote VPS uses LUKS full-disk encryption and only boots after the passphrase is entered. dropbear-initramfs accepts that passphrase over SSH; this script sends it.
- Python 3.11+ and Poetry (
python3 -m pip install -U --user poetry) - SSH keyfile
- Install and configure dropbear-initramfs.
- Setup:
poetry install --only=main(once) - Security:
ssh-keyscan -p SSH_HOST_PORT SSH_HOST_IP > host_keys(pins the host's SSH public key so the script only sends the passphrase to the genuine dropbear server; hinders man-in-the-middle attacks) - Configuration:
cp env.template .envand set IP, port, keyfile, passphrase and notification e-mail (boolean values accept1/true/yes/onand0/false/no/off) thenchmod 600 .env(it contains the passphrase; the script refuses to run otherwise) - Optional: set up the CSV control and
SUL_CONTROL_CSV_URL - Check/test:
poetry run python ssh_unlock_luks.py - Cron job:
*/5 * * * * flock -n /run/lock/ssh_unlock_luks.lock sh -c 'cd /opt/SSHUnlockLUKS/ && .venv/bin/python ssh_unlock_luks.py 2>/dev/null'(flock -nprevents overlapping runs; the lock file must be writable by the cron user, otherwise use e.g./tmp/ssh_unlock_luks.lock)
With SUL_DOWN_ALARM_MINUTES set, one e-mail is sent when the production SSH port (SUL_PROD_SSH_PORT)
has been closed for longer than that, plus a recovery notice. The outage start is stored in
SUL_STATE_FILE (default ~/.local/state/ssh_unlock_luks/state.json, honours XDG_STATE_HOME; not in /tmp).
Resolution equals the cron interval. Parallel runs are blocked by a flock on <state file>.lock.
--dry-run only previews mails and writes no state.
With SUL_UNLOCK_MAX_DOWN_MINUTES (e.g. 15), the script stores last_seen_open in the state file.
If the port was last open longer ago than the limit, the passphrase is not sent, even if the CSV says yes.
Instead one alarm e-mail is sent and the exit code is 2. This guards against a forgotten yes after an
unexpected reboot. Without a stored timestamp (first run), unlocking is not blocked.
After a verified planned reboot, either set the CSV flag to yes! or run python ssh_unlock_luks.py --reset-last-seen.
Keep the cron interval clearly below the limit.
An attacker with control over the unencrypted /boot could get the passphrase sent to a manipulated
system at the next planned reboot. LUKS and Clevis/Tang do not fully protect against this.
The CSV flag is the manual arming switch. Check /boot by hand before setting it to yes:
# Baseline, after every kernel/initramfs/GRUB update
ssh root@VPS 'sha256sum /boot/vmlinuz-* /boot/initrd.img-* /boot/grub/grub.cfg' > ~/boot-baseline.txt
# Before a planned reboot
ssh root@VPS 'sha256sum /boot/vmlinuz-* /boot/initrd.img-* /boot/grub/grub.cfg' \
| diff - ~/boot-baseline.txt && echo "boot files unchanged" || echo "DIFFERENT - do not arm the unlock"This only detects changes made before the check, so it reduces the risk but does not eliminate it.
If SUL_CONTROL_CSV_URL is set, the script downloads the CSV and checks for its host. This lets the
owner approve each unlock centrally.
- Create a CSV with the columns
HOST,UNLOCK_FLAG. - Host it on a web server.
- Set
SUL_CONTROL_CSV_URLin.env.
| HOST | UNLOCK_FLAG |
|---|---|
| 1.2.3.4 | yes |
| 11.22.33.1 | no |
HOSTmust matchSUL_SSH_IP.UNLOCK_FLAG:yes,1ortrueunlocks.yes!also overrides the last-seen block for that run. Use it only after a verified reboot, then set it back tono.--forceon the command line skips the CSV check entirely for that run. The last-seen block still applies.
Each unlock attempt (success or failure) sends an e-mail via the local MTA (Postfix, Exim or any sendmail-compatible binary). "Nothing to do" cases send no mail.
SUL_MAIL_TOis mandatory.- Optional:
SUL_MAIL_FROM(if unset, noFrom:header is set and the local MTA uses its system default sender, likemail) andSUL_MAIL_SUBJECT. --dry-runsends nothing. It logs the mail and saves it as an.emlfile under/tmp.
A missing sendmail or failed delivery only logs a warning and does not change the exit code.
- Mandos: closest in functionality, pull model with TLS/OpenPGP, approval options. Server must be reachable from the internet.
- Clevis + Tang: no stored passphrase, but the Tang server must be reachable from the VPS. No manual release switch.
- dracut-crypt-ssh, dracut-sshd: for dracut-based distributions.
remote-unlock(passphrase frompass)unlock-cryptroot(interactive)dropbear-auto-unlock(ZFS only, no LUKS)