LUKS remote unlock over SSH: dropbear-initramfs and cryptroot-unlock

Short answer: install `dropbear-initramfs`, put your SSH public key in `/etc/dropbear/initramfs/authorized_keys` (Debian 12/13, Ubuntu 24.04), give the initramfs a network config, run `update-initramfs -u` and reboot. While the server waits for the passphrase, SSH into the tiny Dropbear server on its own port and run `cryptroot-unlock`; the boot then continues normally.

This guide assumes the root filesystem is already on LUKS, as set up in the LUKS encrypted root guide, and that `/boot` is unencrypted, which is the Debian and Ubuntu installer default. It works on any KVM VPS where you control the kernel and initramfs, and it is a sensible base before you put services like those in a small-VPS self-hosting stack on the disk.

How remote unlock works

On an encrypted-root system the kernel first loads an initramfs, a small temporary root filesystem stored unencrypted in `/boot`. Its job is to find the LUKS device, ask for the passphrase, open it and hand over to the real root. Normally the prompt appears only on the local console.

`dropbear-initramfs` adds three things to that initramfs: the Dropbear SSH server, a network setup step, and the `cryptroot-unlock` helper. Dropbear starts before the passphrase prompt, accepts only public-key logins from the keys you baked in, and `cryptroot-unlock` forwards your passphrase to the waiting `cryptsetup` prompt. After the root is opened, the initramfs kills Dropbear and your real OpenSSH server starts as usual.

File paths differ between versions

The configuration directory moved when Dropbear 2022.83 landed. Many older tutorials still show the old path, and a key placed there is silently ignored on current releases. Check your release before copying commands.

Note · The options file is `dropbear.conf` in the same directory on every release. The initramfs host keys also live there (`dropbear_ed25519_host_key` and friends) and are separate from the OpenSSH host keys of the running system.

Step-by-step setup on Debian 12/13 and Ubuntu 24.04

1. 01.Install the package: `apt install dropbear-initramfs`. A warning about a missing or invalid `authorized_keys` file at this point is expected.
2. 02.Add your public key, ideally a dedicated Ed25519 key, to `/etc/dropbear/initramfs/authorized_keys`, one key per line, and restrict it so the only thing it can do is unlock.
3. 03.Set Dropbear options in `/etc/dropbear/initramfs/dropbear.conf`, including a non-default port so the initramfs host key does not clash with your normal SSH host key in `known_hosts`.
4. 04.Configure the network for the initramfs with the `ip=` kernel parameter (static) or rely on DHCP if your VPS network supports it.
5. 05.Rebuild the initramfs with `update-initramfs -u` and, if you changed the kernel command line, run `update-grub`.
6. 06.Reboot with console access open as a fallback, then connect and run `cryptroot-unlock`.

apt install dropbear-initramfs

# 1. Key (forced command: the key can only unlock)
echo 'no-port-forwarding,no-agent-forwarding,no-X11-forwarding,command="/bin/cryptroot-unlock" ssh-ed25519 AAAA...yourkey unlock@laptop' \
  > /etc/dropbear/initramfs/authorized_keys
chmod 600 /etc/dropbear/initramfs/authorized_keys

# 2. Options in /etc/dropbear/initramfs/dropbear.conf
#    -p 2222  listen on port 2222
#    -s       disable password logins
#    -j -k    no local/remote port forwarding
#    -I 300   drop idle sessions after 300 s
DROPBEAR_OPTIONS="-p 2222 -s -j -k -I 300"

# 3. Rebuild
update-initramfs -u

Network configuration in the initramfs

The initramfs does not read `/etc/network/interfaces`, netplan or systemd-networkd. It uses the kernel `ip=` parameter, or the `IP=` line in `/etc/initramfs-tools/initramfs.conf`. With neither set, it tries DHCP on all interfaces, which works on many clouds but is not guaranteed on a VPS with a static assignment.

The format is `ip=<client-ip>::<gateway-ip>:<netmask>:<hostname>:<device>:off`. Use the values from `ip -4 addr` and `ip route` on the running system. The interface name inside the initramfs is usually the same predictable name (for example `ens3` or `eth0`); if unsure, leave the device field empty and the first interface is used. IPv4 is the reliable choice here, since IPv6 support in the initramfs network step is limited.

# /etc/default/grub (static IPv4 example, documentation addresses)
GRUB_CMDLINE_LINUX="ip=203.0.113.10::203.0.113.1:255.255.255.0::ens3:off"

update-grub
update-initramfs -u

# From your workstation after reboot:
ssh -p 2222 [email protected]
# without the forced command, type: cryptroot-unlock

Unlocking and day-to-day use

After a reboot, wait until the server answers on port 2222, then connect as `root`. With the forced command from the setup step, `cryptroot-unlock` starts immediately and asks for the LUKS passphrase; without it, you get a BusyBox shell and type `cryptroot-unlock` yourself. On success the session closes, the initramfs continues booting, and a minute later your regular SSH server answers on port 22, hardened as in the SSH hardening guide.

Use a separate `known_hosts` entry for the unlock port, for example a `Host myserver-unlock` block in `~/.ssh/config` with `Port 2222` and `HostKeyAlias myserver-unlock`. Every time the kernel updates, Debian and Ubuntu regenerate the initramfs and keep your Dropbear key and options, but test one reboot after major upgrades.

• ▹Connection refused: the network config is wrong; check the `ip=` values on the console.
• ▹Host key warning: you are hitting the initramfs host key under the normal alias; use the separate alias.
• ▹`cryptroot-unlock` says no devices are waiting: the system already booted, or `/etc/crypttab` lacks the root entry.
• ▹Key changes have no effect: you edited the old `/etc/dropbear-initramfs/` path or forgot `update-initramfs -u`.

Threat model: what remote unlock does and does not protect

LUKS with remote unlock protects data at rest. A powered-off disk, a copied disk image, a decommissioned drive or a server seized while shut down reveals only ciphertext. That is a real and useful guarantee for a VPS.

It does not protect a running server from whoever controls the host. The initramfs and kernel in `/boot` are unencrypted, so someone with hypervisor or console access can modify them to record your passphrase on the next boot, and a running VM's memory, including the LUKS master key, can be read from the host. Treat remote unlock as protection against seizure and disk leaks, not against a hostile hypervisor. Reboot-time anomalies, such as a changed Dropbear host key, are worth investigating.

Note · On a NoctisNode VPS you get full root on KVM with the Debian 13/12 and Ubuntu 24.04 images, so this setup works as described. The same limit applies here as everywhere: encryption protects the disk, not a running guest. See no-logs VPS explained for what the provider side does and does not record.

FAQ