How to install Debian on an existing LUKS container

LUKS (Linux Unified Key Setup) is the de-facto standard encryption method used on Linux-based systems. While the Debian installer is perfectly capable of creating a LUKS container, it lacks the ability to recognize and therefore re-use an already existing one. In this article we see how we can workaround this problem using the “DVD1” installer, and running it in “advanced” mode.

In this tutorial you will learn:

  • How to install Debian in “advanced-mode”
  • How to load the installer additional modules needed to unlock an existing LUKS device
  • How to perform the installation on an existing LUKS container
  • How to add an entry in the crypttab file of the newly installed system and regenerate its initramfs

How to install Debian on an existing LUKS container

How to install Debian on an existing LUKS container

Software requirements and conventions used

Software Requirements and Linux Command Line Conventions
Category Requirements, Conventions or Software Version Used
System Debian
Software No specific software needed
Other The Debian DVD installer
Conventions # – requires given linux-commands to be executed with root privileges either directly as a root user or by use of sudo command
$ – requires given linux-commands to be executed as a regular non-privileged user

The problem: re-using an existing LUKS container

As we already said, the Debian installer is perfectly capable of creating and installing the distribution on a LUKS container (one typical setup is LVM on LUKS), however it can’t currently recognize and open an already existing
one; why we would need this feature? Suppose, for example, we already created a LUKS container manually, with some encryption settings which can’t be fine-tuned from the distribution installer, or imagine we have some logical volume inside the container which we don’t want to destroy (perhaps it contains some data); by using the installer standard procedure, we would be forced to create a new LUKS container, and so to destroy the existing one. In this tutorial we will see how, with few extra steps, we can we workaround this problem.

Downloading the DVD installer

To be able to perform the actions described in this tutorial we must download and use the Debian DVD installer, since it contains some libraries which are not available in the netinstall version. To download the installation image via torrent we can use one of the links below, depending on the architecture of our machine:

From the links above we can download the torrent files we can use to obtain the image of the installer. What we have to download is the DVD1 file. To obtain the installation ISO, we must use a torrent client as Transmission. Once the image is downloaded, we can verify it verify by downloading the corresponding SHA256SUM and SHA256SUM.sign files and follow this tutorial about how to verify the integrity of a Linux distribution iso image. When ready, we can write the image on a support which can be used as a boot device: either a (DVD or USB), and boot our machine from it.

Using the advanced installation mode

When we boot the machine using the device we prepared, we should visualize the following syslinux menu:


We select the Advanced options entry, and then Graphical expert install (or Expert install if we want to use the ncurses-based installer, which uses less resources):


Once we select and confirm the menu entry, the installer will start and we will visualize the list of the installation steps:


We follow the installation steps until we arrive on the Load installer components from CD one. Here we have the change to select the additional libraries which should be loaded by the installer. The minimum we want to select from the list is Crypto-dm-modules and rescue-mode (scroll down the list to see it):


Manually unlocking the existing LUKS container and partitioning the disk

At this point we can proceed as usual until we arrive on the Detect disks step. Before we perform this step we need to switch to a tty and open the existing LUKS container from the command line. To do this, we can press the Ctrl+Alt+F3 keys combination and press Enter to obtain a prompt. From the prompt we open the LUKS device by launching the following command:

# cryptsetup luksOpen /dev/vda5 cryptdevice
Enter passphrase for /dev/vda5:

In this case the LUKS device was previously set on the /dev/vda5 partition, you should of course, adapt this to your needs. We will be asked to enter the passhprase for the container in order to unlock it. The device mapper name we use here (cryptdevice) is what we will need to use later in the /etc/crypttab file.

Once this step is performed, we can switch back to the installer (Ctrl+Alt+F5) and proceed with the Detect disks and then with Partition disks steps. In the Partition disks menu we select the “Manual” entry:


The unlocked LUKS device and the logical volumes contained in it should appear in the list of the available partitions, ready to be used as targets for our system setup. Once we are ready we can continue with the installation until we arrive on the Finish the installation step. Before performing it we need to create an entry in the newly installed system crypttab for the LUKS device, since it is not created by default, and recreate the system initramfs to make the change effective.

Creating an entry in /etc/crypttab and recreating the initramfs

Let’s switch back to the tty we used before (Ctrl+Alt+F3). What we need to do now, is to manually add an entry in the /etc/crypttab file of the newly installed system for the LUKS device. To do that, we must mount the root partition of the new system somewhere (let’s use the /mnt directory) and mount some pseudo-filesystems which provide important information on the appropriate directories inside of it. In our case the root filesystem is in the /dev/debian-vg/root logical volume:

# mount /dev/debian-vg/root /mnt
# mount /dev /mnt/dev
# mount /sys /mnt/sys
# mount /proc /mnt/proc

Since in this case we have a separate boot partition (/dev/vda1), we also need to mount it on /mnt/boot:

# mount /dev/vda1 /mnt/boot

At this point we must chroot into the installed system:

# chroot /mnt

Finally, we can open the /etc/crypttab file with one of the available text editors, (vi for example), and add the following entry:

cryptdevice /dev/vda5 none luks

The first element in the line above is the device mapper name we used above when we unlocked the LUKS container manually; it will be used each time the container is opened during the system boot.

The second element is the partition which is used as LUKS device (in this case we referenced it by path (/dev/vda5), but a better idea would be to reference it via UUID).

The third element is the location of the key file used to open the container: here we put none as we don’t use one (follow our tutorial about How to use a file as a LUKS device key if you want to know how to achieve this kind of setup).

The last element in the line hosts the options which should be used for the encrypted device: here we just used luks to specify that the device is a LUKS container.

Once we updated the /etc/crypttab file, we can proceed further and regenerate the initramfs. On Debian and debian-based distributions, to perform this action we use the update-initramfs command:

# update-initramfs -k all -c

Here we used the -c option to instruct the command to create a new initramfs instead of updating an existing one, and -k to specify for what kernel the initramfs should be created. In this case we passed all as argument, so one for every existing kernel will be generated.

Once the initramfs is generated, we switch back to the installer (Ctrl+Alt+F5) and proceed with the last step: Finish the installation. When the installation we will be prompted the reboot to access the newly installed system. If everything went as expected, during the system boot, we should be prompted to enter the passphrase to unlock the LUKS container:



In this tutorial we learned how to workaround a limitation of the Debian installer which is not capable to recognize and open an existing LUKS container to perform the system installation inside of it. We learned how to use the installer in “Advanced mode” to be able to load some additional modules which allow us to unlock the container manually by switching to a tty. Once the container is opened it is correctly recognized by the installer and can be used without problems. The only tricky part of this setup is that we must remember to create an entry for the container in the newly installed system crypttab file, and update its initramfs.