What is LUKS / full disk encryption?

LUKS is a Linux software that is commonly used to encrypt files / disks on Linux systems such as Ubuntu/Debian/CentOS/Redhat (RHEL)/Fedora - it can be used both to encrypt a single folder using an image file / LVM volume, or can be used to encrypt your entire disk.

With full disk encryption, by default - to unlock the disk, you're expected to have physical or virtual access to the console of the system - i.e. the default display + keyboard that the system uses, such as a physical monitor, or virtual VGA / serial console.

This guide explains how you can setup dropbear-initramfs and initramfs networking which will allow you to connect to your Linux system via SSH during the early boot process, allowing you to unlock your disk remotely via SSH without needing console access to the system.

Setting up dropbear-initramfs

Please be aware that this guide is oriented towards Debian-based distros such as Debian and Ubuntu.

Fedora/Redhat/CentOS does not provide the dropbear-initramfs package, which makes the setup more complicated, if you're on a redhat based distro and are experienced working with Linux, you can check out this StackOverflow answer which includes a link to a dracut module designed to integrate dropbear

Install the dropbear-initramfs package

First you'll need to install the package:

sudo apt update
sudo apt install dropbear-initramfs

You can ignore the warning about the authorized_keys file, you'll be adding your key shortly.

Add your SSH key to the authorized_keys file

If you care enough about your security/privacy to setup disk encryption, we assume you should know how to generate and use SSH keys, so we won't be explaining how to generate one here.

As dropbear is based off of an older version of SSH, please note that it does not support modern ed25519 keys. We recommend using a standard RSA 4096 or 2048 key to avoid issues.

Open the dropbear authorized_keys file and paste in an SSH RSA public key (e.g. copy the contents of your ~/.ssh/id_rsa.pub file and paste it in there)

sudo nano /etc/dropbear-initramfs/authorized_keys

Save and close the file.

Configure Dropbear

Open the dropbear config in your preferred editor, such as nano:

sudo nano /etc/dropbear-initramfs/config

And change "DROPBEAR_OPTIONS" to:

DROPBEAR_OPTIONS="-I 300 -j -k -p 2222 -s"

-I 300 sets the inactivity timeout to 300 seconds, i.e. if you don't type anything for 5 mins you'll be disconnected. -j and -k disables SSH local and remote port forwarding respectively. -p 2222 means run the dropbear server on port 2222. -s disables password authentication (important for security!).

This configuration will result in you being dropped into a BusyBox shell upon connection, which is helpful if you need to troubleshoot things during the early boot stages, such as a broken mount.

If you'd rather it immediately asks you for your LUKS password, add -c cryptroot-unlock to the end of the DROPBEAR_OPTIONS before the end quote.

Configure IPv4 connectivity

If your server is IPv6-only, please skip this and go to Configure IPv6 connectivity.

If your system gets it's IPv4 address via DHCP, this step is optional, as dropbear-initramfs is preconfigured to run DHCP during boot if you don't configure an IPv4 address.

Open the initramfs config file in your preferred editor:

sudo nano /etc/initramfs-tools/initramfs.conf

At the end of the file, add the following line, and replace the example IPs with your real static IP information:

# IP_ADDRESS::GATEWAY:NETMASK:HOSTNAME
IP=10.0.0.5::10.0.0.1:255.255.255.0:myserver

Save and close the file.

Configure IPv6 connectivity

If your server doesn't have IPv6 connectivity, or you don't care about having IPv6 during early boot to unlock LUKS, you may skip this step.

Unfortunately, initramfs config doesn't natively have IPv6 support, however, it's possible to add IPv6 support using a custom set of initramfs scripts, which we'll guide you through installing:

Install IPv6 initramfs scripts

Credit: these scripts were originally based off of a [Gist made by the Github user "zajdee", we fixed a few issues with it and added more debug logging

Download the initramfs scripts into their respective locations, and mark them as executable:

wget -O /etc/initramfs-tools/hooks/ipv6 https://gist.github.com/Someguy123/8092bdc9834aa210fb4bd1523e9a1c38/raw/c4b846675b1736a8f7e44ccf317241a73960c119/debian-initramfs-ipv6-hook-script
wget -O /etc/initramfs-tools/scripts/init-premount/ipv6 https://gist.github.com/Someguy123/8092bdc9834aa210fb4bd1523e9a1c38/raw/c4b846675b1736a8f7e44ccf317241a73960c119/debian-initramfs-ipv6-premount-script
chmod +x /etc/initramfs-tools/{hooks,scripts/init-premount}/ipv6

Update Linux kernel command line to include IPv6 static IP details

On Ubuntu and Debian, the kernel command line is handled by GRUB, you need to edit the GRUB default config to add your IPv6 configuration to be used during early boot.

Open the file /etc/default/grub with your preferred editor:

nano /etc/default/grub

Find the line starting with GRUB_CMDLINE_LINUX (not the _DEFAULT one), or add a new one, and edit it to contain your IPv6 configuration as follows:

#   Syntax: ipv6=addr=<address>/<netmask>,gw=<gateway>,iface=<interface>,forwarding=<0/1>,accept_ra=<0/1/2>
GRUB_CMDLINE_LINUX="ipv6=addr=2a07:e00::333/64,gw=fe80::1,iface=ens18,forwarding=0,accept_ra=0"

Adjust the address, gateway, and interface to your actual static IPv6 address + gateway + interface.

Now save and close the file.

Re-generate your initramfs + GRUB config

For your edited configurations to actually take effect, you need to re-generate your initramfs and GRUB config by running the following commands:

sudo update-initramfs -u
sudo update-grub

After running these, you should be pretty much good to go!

Reboot and test it out!

Now you need to reboot your system and verify it actually works.

Run the following command to reboot your server:

sudo reboot

Wait for your server to boot back up, this may take anywhere from 1 to 10 minutes.

Assuming you didn't change the dropbear port, you should be able to connect to your server via SSH as root on port 2222, via IPv4 or IPv6:

# Connect via IPv4
ssh -p 2222 [email protected]
# Connect via IPv6
ssh -p 2222 root@2a07:e00::333

If you get "Permission denied (publickey)" and you're sure you're using the right public key, see the next section about this error and how to fix it, then come back to this section.

Once you're connected, unless you added -c cryptroot-unlock to the dropbear config (in which case you'll be immediately prompted for your password), you'll be dropped into a BusyBox shell that looks like this:

BusyBox v1.30.1 (Ubuntu 1:1.30.1-4ubuntu6.4) built-in shell (ash)
Enter 'help' for a list of built-in commands.

#

To unlock your disk, enter the command cryptoroot-unlock and hit enter, then enter your encryption password when prompted and hit enter again:

# cryptroot-unlock
Please unlock disk dm_crypt-0:
cryptsetup: dm_crypt-0 set up successfully

Assuming you entered the correct password, you should get disconnected from SSH, and your server should now be booting into the operating system. Wait 30 seconds (or more) and you should be able to connect to the real SSH of your server, and access any other services on your server.

Congratulations! You've successfully setup dropbear-initramfs, and should be able to unlock your disk via SSH without needing a console every time you reboot :)

HELP: I'm getting "Permission denied (publickey)" even though everything looks correct

If you get the error "Permission denied (publickey)" when connecting to your dropbear SSH during boot, but you're certain you're using the correct SSH key and entered it correctly into dropbear's authorized_keys file, the issue is likely due to Dropbear being based off of an older SSH version, while your SSH client is very modern and no longer allows older less-secure public keys.

To get around this with the OpenSSH client (ssh command), you simply need to add the flag -o PubkeyAcceptedAlgorithms=+ssh-rsa to the start of your ssh command, which will tell your SSH client to trust ssh-rsa and should allow you to connect:

ssh -o PubkeyAcceptedAlgorithms=+ssh-rsa -p 2222 [email protected]

If you're using a different SSH client, you'll need to search online to find out how to set that flag with your specific SSH client.

Thanks for reading!