Blog about software development


LUKS recovery from initramfs shell

17 Jul 2023 - by 'Maurits van der Schee'

When writing LUKS tutorials I often made mistakes preventing my system to boot. This resulted in a dreadful message saying:

ALERT! /dev/mapper/debian--vg-root does not exist.  Dropping to a shell!

Showing me a BusyBox shell and a prompt that looks like this:

BusyBox v1.30.1 (Debian 1:1.30.1-6+b3) built-in shell (ash) 
Enter 'help' for a list of built-in commands.


In this post I will describe how to quickly mount your root partition from the initramfs shell and also how to easily correct bigger problems using Debian's Rescue mode.

Unlocking from initramfs shell

If you do end up in the initramfs shell you need to type the following command:

cat /cryptroot/crypttab

Since the file "/etc/crypttab" is available as "/cryptroot/crypttab" in initramfs it shows something like:

vda5_crypt UUID=eee31528-256c-11ee-990f-b7ff89c85428 none luks,discard

Now after the mapper device you see a UUID. Take the UUID from the above output and run:

readlink -f /dev/disk/by-uuid/eee31528-256c-11ee-990f-b7ff89c85428

You now see the physical device, so somethings like:


Now you can unlock the root partition using the physical device and the mapper device:

cryptsetup luksOpen /dev/vda5 vda5_crypt

And now you can type one of the valid passphrases at the prompt:

Enter passphrase for /dev/vda5: 

After this is accepted you need to continue the boot using "exit":


And the system should boot.

Using Debian Rescue mode

You can boot the Debian 12 (netinst) install image and it has "Advanced options" and then "Rescue mode" as option. After asking a bunch of simple questions about your language, location, keyboard and network setup and (temporary) hostname you are asked for the passphrase of the root device. After that you should choose "Yes" to also mount the boot partition. Now the first option is:

Execute a shell in /dev/debian-vg/root

If you choose that option then all you have to do to correct the misconfigured "/etc/crypttab" is:

nano /etc/crypttab
update-initramfs -u

And the menu is presented again. You can now reboot.


If you make a mistake in your "/etc/crypttab" or other initramfs configuration files and you are using LUKS on LVM, then don't worry. Debian's Rescue mode is very smart and helps you with the otherwise manual steps of LVM2 scanning, LUKS unlocking, mounting root and boot and mounting proc and sys and binding dev. It does provide you with a "chroot"-ed environment so you can easily repair and regenerate your initramfs configuration, including your LUKS configuration.

Related / Links


PS: Liked this article? Please share it on Facebook, Twitter or LinkedIn.