Remote Unlock of LUKS-Encrypted Root Disk via SSH

This document outlines how to configure remote unlocking of an encrypted root filesystem protected by LUKS during system boot, using SSH access before the main OS loads.

Remote SSH Unlock Using Tailscale

Remote unlocking via Tailscale works by running the Tailscale client inside the initramfs early boot environment. This allows you to SSH into the machine over your Tailscale tailnet before the encrypted root filesystem is unlocked.

These instructions assume you already have Tailscale installed and configured normally on your system.

  1. Add the tailscale-initramfs repository and install the package:

sudo mkdir -p --mode=0755 /usr/local/share/keyrings
curl -fsSL https://darkrain42.github.io/tailscale-initramfs/keyring.asc | sudo tee /usr/local/share/keyrings/tailscale-initramfs-keyring.asc >/dev/null
echo 'deb [signed-by=/usr/local/share/keyrings/tailscale-initramfs-keyring.asc] https://darkrain42.github.io/tailscale-initramfs/repo stable main' | sudo tee /etc/apt/sources.list.d/tailscale-initramfs.list >/dev/null
sudo apt-get update
sudo apt-get install tailscale-initramfs

  1. Generate a Tailscale ephemeral auth key for the initramfs client:

  • Go to your Tailscale Admin Console.

  • Create an ephemeral auth key with a suitable expiration (up to 90 days).

  • Assign ACL tags to restrict the initramfs client's access to only inbound SSH connections for security.

  1. Configure the auth key on your system by placing it into the file /etc/tailscale/initramfs/config:

--authkey=tskey-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
--hostname=your-hostname-initramfs
--accept-routes=false
--accept-dns=false
--exit-node=false

Modify options as needed, but ensure the authkey is included.

  1. Rebuild all the initramfs images to embed the Tailscale client and your configuration:

sudo update-initramfs -c -k all

  1. Reboot your system:

sudo reboot

During boot, the initramfs environment will start the embedded Tailscale client, which will connect to your tailnet using the ephemeral key.

  1. SSH to your machine via its Tailscale IP or hostname from another device connected to the same tailnet:

ssh root@your-hostname-initramfs

  1. Once connected, run the unlock command to enter the LUKS passphrase and continue the system boot:

cryptroot-unlock

  1. Maintain your setup by renewing and updating the ephemeral auth key before it expires (keys last up to 90 days), or you risk losing remote unlock access.

At this point, when your system boots, it will connect to your Tailscale network during initramfs phase, allowing SSH access over Tailscale.

You can SSH into the machine using its Tailscale IP or hostname and run cryptroot-unlock remotely to enter the LUKS passphrase and continue booting.

Because the Tailscale client in initramfs uses an ephemeral auth key, make sure to renew and update the key in the initramfs before it expires to avoid losing remote access.

Using Tailscale in early boot removes the need for static IP or port forwarding setups since it leverages Tailscale’s private mesh VPN network for connectivity.

This setup is ideal for remote servers or devices behind NAT where direct network access is limited or insecure.

Prerequisite Requirement without Tailscale: Static or Reserved IP Address

Reliable remote unlocking requires that your system has a static IP address or a DHCP reservation that ensures the IP address remains constant between reboots.

  • The SSH server started in the early boot environment (initramfs) must be reachable at a known IP to connect and provide the LUKS passphrase remotely.

  • Changing IP addresses (dynamic DHCP without reservation) will likely prevent connecting to the system for remote unlock.

  • Setting a static IP or DHCP reservation is critical for both Debian (dropbear-initramfs) and Fedora (dracut-sshd) setups.

Debian and Debian-Based Systems (e.g., Ubuntu)

Prerequisites

  • LUKS-encrypted root filesystem with unencrypted /boot.

  • SSH key pair for authentication.

  • Root access to the system.

  • Static or DHCP-reserved IP address configured for early boot networking.

Steps

1. Copy Your SSH Key to the System

ssh-copy-id -i /root/.ssh/id_rsa root@<system-ip>

2. Install Dropbear in Initramfs

apt install dropbear-initramfs

Dropbear is a lightweight SSH server designed for early boot environments.

3. Configure Network for Initramfs

Add a static IP configuration for the network interface inside /etc/initramfs-tools/initramfs.conf:

cat << 'EOF' >> /etc/initramfs-tools/initramfs.conf
IP=<system-ip>::<gateway-ip>:<netmask>::<interface>:off
EOF

Use the same IP that your system uses normally to maintain consistent access.

4. Add SSH Public Keys for Dropbear

cp /root/.ssh/authorized_keys /etc/dropbear/initramfs/authorized_keys
chmod 600 /etc/dropbear/initramfs/authorized_keys

5. Update Initramfs and Reboot

update-initramfs -u
reboot

You may see messages about unresolved devices related to cryptsetup; these are normal until unlocking.

6. Unlock via SSH at Boot

ssh root@<system-ip>
cryptroot-unlock

Enter your LUKS passphrase when prompted to unlock the disk and continue boot.

Fedora and Similar RPM-Based Systems

Prerequisites

  • LUKS-encrypted root filesystem.

  • SSH key pair.

  • Root or sudo access.

  • Static or DHCP-reserved IP address configured for early boot networking.

Steps

1. Install dracut-sshd

sudo dnf install dracut-sshd

2. Enable dracut-sshd Service for Initramfs

sudo systemctl enable dracut-sshd.socket

This enables an OpenSSH server to start in the initramfs environment during boot.

3. Configure Network and Firewall

  • Configure a static IP for your system normally.

  • Ensure network configuration allows SSH connections during early boot.

  • Optional: Edit dracut configuration to ensure network is brought up early.

4. Regenerate Initramfs

sudo dracut -f

5. Reboot System

sudo reboot

6. SSH and Unlock

When the system is rebooting and waiting for LUKS unlock:

ssh <user>@<system-ip>

Run the unlocking command as appropriate (often cryptroot-unlock or as specified in your system).

Notes and Best Practices

  • Use SSH key authentication exclusively for security.

  • Firewall rules must allow incoming SSH connections during early boot.

  • For environments where IP addresses may change, consider DHCP reservations to guarantee consistent IP assignment.

  • Physical or out-of-band access is a fallback if network unlocking fails due to address misconfiguration.

  • This setup is intended for headless or remotely-managed servers where physical console access is difficult.

PreviousExpose the Web UI over TailnetNextGit

Last updated