Antoine Beaupr : Encrypting a Debian install with UKI
I originally setup a machine without any full disk encryption, then
somehow regretted it quickly after. My original reasoning was that
this was a "play" machine so I wanted as few restrictions on accessing
the machine as possible, which meant removing passwords, mostly.
I actually ended up having a user password, but disabled the lock
screen. Then I started using the device to manage my photo collection,
and suddenly there was a lot of "confidential" information on the
device that I didn't want to store in clear text anymore.
Pre-requisites
So, how does one convert an existing install from plain text to full
disk encryption? One way is to backup to an external drive,
re-partition everything and copy things back, but that's slow and
boring. Besides,
Pre-requisites
So, how does one convert an existing install from plain text to full
disk encryption? One way is to backup to an external drive,
re-partition everything and copy things back, but that's slow and
boring. Besides, cryptsetup has a cryptsetup-reencrypt command,
surely we can do this in place?
Having not set aside enough room for /boot, I briefly
considered a "encrypted /boot" configuration and conversion (e.g. with
this guide) but remembered grub's support for this is flaky, at
best, so I figured I would try something else.
Here, I'm going to guide you through how I first converted from grub
to systemd-boot then to UKI kernel, then re-encrypt my main
partition.
Note that secureboot is disabled here, see further discussion below.
systemd-boot and Unified Kernel Image conversion
systemd folks have been developing UKI ("unified kernel image")
to ship kernels. The way this works is the kernel and initrd (and UEFI
boot stub) in a single portable executable that lives in the EFI
partition, as opposed to /boot. This neatly solves my problem,
because I already have such a clear-text partition and won't need to
re-partition my disk to convert.
Debian has started some preliminary support for this. It's not
default, but I found this guide from Vasudeva Kamath which was
pretty complete. Since the guide assumes some previous configuration,
I had to adapt it to my case.
Here's how I did the conversion to both systemd-boot and UKI, all at
once. I could have perhaps done it one at a time, but doing both at
once works fine.
Before your start, make sure secureboot is disabled, see the
discussion below.
- install systemd tools:
apt install systemd-ukify systemd-boot
- Configure
systemd-ukify, in /etc/kernel/install.conf:
layout=uki
initrd_generator=dracut
uki_generator=ukify
TODO: it doesn't look like this generates a initrd with dracut, do
we care?
- Configure the kernel boot arguments with the following in
/etc/kernel/uki.conf:
[UKI]
Cmdline=@/etc/kernel/cmdline
The /etc/kernel/cmdline file doesn't actually exist here, and
that's fine. Defaults are okay, as the image gets generated from
your current /proc/cmdline. Check your /etc/default/grub and
/proc/cmdline if you are unsure. You'll see the generated
arguments in bootctl list below.
- Build the image:
dpkg-reconfigure linux-image-$(uname -r)
- Check the boot options:
bootctl list
Look for a Type #2 (.efi) entry for the kernel.
- Reboot:
reboot
You can tell you have booted with systemd-boot because (a) you won't
see grub and (b) the /proc/cmdline will reflect the configuration
listed in bootctl list. In my case, a systemd.machine_id variable
is set there, and not in grub (compare with /boot/grub/grub.cfg).
By default, the systemd-boot loader just boots, without a menu. You
can force the menu to show up by un-commenting the timeout line in
/boot/efit/loader/loader.conf, by hitting keys during boot
(e.g. hitting "space" repeatedly), or by calling:
systemctl reboot --boot-loader-menu=0
See the systemd-boot(7) manual for details on that.
I did not go through the secureboot process, presumably I had
already disabled secureboot. This is trickier: because one needs a
"special key" to sign the UKI image, one would need the collaboration
of debian.org to get this working out of the box with the
keys shipped onboard most computers.
In other words, if you want to make this work with secureboot enabled
on your computer, you'll need to figure out how to sign the generated
images before rebooting here, because otherwise you will break your
computer. Otherwise, follow the following guides:
- Enabling Secure Boot with UKI on Debian
- Disabling Lockdown Mode with Secure Boot on Distro Kernel
- Signing the systemd-boot on Upgrade Using Dpkg Triggers
Re-encrypting root filesystem
Now that we have a way to boot an encrypted filesystem, we can switch
to LUKS for our filesystem. Note that you can probably follow this
guide if, somehow, you managed to make grub work with your LUKS setup,
although as this guide shows, you'd need to downgrade the
cryptographic algorithms, which seems like a bad tradeoff.
We're using cryptsetup-reencrypt for this which, amazingly, supports
re-encrypting devices on the fly. The trick is it needs free space at
the end of the partition for the LUKS header (which, I guess, makes it
a footer), so we need to resize the filesystem to leave room for that,
which is the trickiest bit.
This is a possibly destructive behavior. Be sure your backups are up
to date, or be ready to lose all data on the device.
We assume 512 byte sectors here. Check your sector size with fdisk
-l and adjust accordingly.
- Before you perform the procedure, make sure requirements are
installed:
apt install cryptsetup systemd-cryptsetup cryptsetup-initramfs
Note that this requires network access, of course.
- Reboot in a live image, I like GRML but any Debian live image
will work, possibly including the installer
- First, calculate how many sectors to free up for the LUKS header
qalc> 32Mibyte / ( 512 byte )
(32 mebibytes) / (512 bytes) = 65536
- Find the sector sizes of the Linux partitions:
fdisk -l /dev/nvme0n1 awk '/filesystem/ print $1 " " $4 '
For example, here's an example with a /boot and / filesystem:
$ sudo fdisk -l /dev/nvme0n1 awk '/filesystem/ print $1 " " $4 '
/dev/nvme0n1p2 999424
/dev/nvme0n1p3 3904979087
- Substract 1 from 2:
qalc> set precision 100
qalc> 3904979087 - 65536
Or, last step and this one, in one line:
fdisk -l /dev/nvme0n1 awk '/filesystem/ print $1 " " $4 - 65536 '
- Recheck filesystem:
e2fsck -f /dev/nvme0n1p2
- Resize filesystem:
resize2fs /dev/nvme0n1p2 $(fdisk -l /dev/nvme0n1 awk '/nvme0n1p2/ print $4 - 65536 ')s
Notice the trailing s here: it makes resize2fs interpret the
number as a 512 byte sector size, as opposed to the default (4k
blocks).
- Re-encrypt filesystem:
cryptsetup reencrypt --encrypt /dev/nvme0n1p2 --resize-device-size=32M
This is it! This is the most important step! Make sure your laptop
is plugged in and try not to interrupt it. This can, apparently,
be resumed without problem, but I'd hate to show you how.
This will show progress information like:
Progress: 2.4% ETA 23m45s, 53GiB written, speed 1.3 GiB/s
Wait until the ETA has passed.
- Open and mount the encrypted filesystem and mount the EFI system
partition (ESP):
cryptsetup open /dev/nvme0n1p2 crypt
mount /dev/mapper/crypt /mnt
mount /dev/nvme0n1p1 /mnt/boot/efi
If this fails, now is the time to consider restoring from backups.
- Enter the
chroot
for fs in proc sys dev ; do
mount --bind /$fs /mnt/$fs
done
chroot /mnt
Pro tip: this can be done in one step in GRML with:
grml-chroot /mnt bash
- Generate a
crypttab:
echo crypt_dev_nvme0n1p2 UUID=$(blkid -o value -s UUID /dev/nvme0n1p2) none luks,discard >> /etc/crypttab
- Adjust root filesystem in
/etc/fstab, make sure you have a line
like this:
/dev/mapper/crypt_dev-nvme0n1p2 / ext4 errors=remount-ro 0 1
If you were already using a UUID entry for this, there's nothing
to change!
- Configure the root filesystem in the
initrd:
echo root=/dev/mapper/crypt_dev_nvme0n1p2 > /etc/kernel/cmdline
- Regenerate UKI:
dpkg-reconfigure linux-image-$(uname -r)
Be careful here! systemd-boot inherits the command line from the
system where it is generated, so this will possibly feature some
unsupported commands from your boot environment. In my
case GRML had a couple of those, which broke the boot. It's still
possible to workaround this issue by tweaking the arguments at
boot time, that said.
- Exit chroot and reboot
exit
reboot
Some of the ideas in this section were taken from this guide but
was mostly rewritten to simplify the work. My guide also avoids the
grub hacks or a specific initrd system (as the guide uses
initramfs-tools and grub, while I, above, switched to dracut and
systemd-boot). RHEL also has a similar guide, perhaps even
better.
Somehow I have made this system without LVM at all,
which simplifies things a bit (as I don't need to also resize the
physical volume/volume groups), but if you have LVM, you need to tweak
this to also resize the LVM bits. The RHEL guide has some information
about this.
/boot. This neatly solves my problem,
because I already have such a clear-text partition and won't need to
re-partition my disk to convert.
Debian has started some preliminary support for this. It's not
default, but I found this guide from Vasudeva Kamath which was
pretty complete. Since the guide assumes some previous configuration,
I had to adapt it to my case.
Here's how I did the conversion to both systemd-boot and UKI, all at
once. I could have perhaps done it one at a time, but doing both at
once works fine.
Before your start, make sure secureboot is disabled, see the
discussion below.
- install systemd tools:
apt install systemd-ukify systemd-boot - Configure
systemd-ukify, in/etc/kernel/install.conf:
TODO: it doesn't look like this generates alayout=uki initrd_generator=dracut uki_generator=ukifyinitrdwith dracut, do we care? - Configure the kernel boot arguments with the following in
/etc/kernel/uki.conf:
The[UKI] Cmdline=@/etc/kernel/cmdline/etc/kernel/cmdlinefile doesn't actually exist here, and that's fine. Defaults are okay, as the image gets generated from your current/proc/cmdline. Check your/etc/default/gruband/proc/cmdlineif you are unsure. You'll see the generated arguments inbootctl listbelow. - Build the image:
dpkg-reconfigure linux-image-$(uname -r) - Check the boot options:
Look for abootctl listType #2 (.efi)entry for the kernel. - Reboot:
reboot
systemd-boot because (a) you won't
see grub and (b) the /proc/cmdline will reflect the configuration
listed in bootctl list. In my case, a systemd.machine_id variable
is set there, and not in grub (compare with /boot/grub/grub.cfg).
By default, the systemd-boot loader just boots, without a menu. You
can force the menu to show up by un-commenting the timeout line in
/boot/efit/loader/loader.conf, by hitting keys during boot
(e.g. hitting "space" repeatedly), or by calling:
systemctl reboot --boot-loader-menu=0
See the systemd-boot(7) manual for details on that.
I did not go through the secureboot process, presumably I had
already disabled secureboot. This is trickier: because one needs a
"special key" to sign the UKI image, one would need the collaboration
of debian.org to get this working out of the box with the
keys shipped onboard most computers.
In other words, if you want to make this work with secureboot enabled
on your computer, you'll need to figure out how to sign the generated
images before rebooting here, because otherwise you will break your
computer. Otherwise, follow the following guides:
- Enabling Secure Boot with UKI on Debian
- Disabling Lockdown Mode with Secure Boot on Distro Kernel
- Signing the systemd-boot on Upgrade Using Dpkg Triggers
Re-encrypting root filesystem
Now that we have a way to boot an encrypted filesystem, we can switch
to LUKS for our filesystem. Note that you can probably follow this
guide if, somehow, you managed to make grub work with your LUKS setup,
although as this guide shows, you'd need to downgrade the
cryptographic algorithms, which seems like a bad tradeoff.
We're using cryptsetup-reencrypt for this which, amazingly, supports
re-encrypting devices on the fly. The trick is it needs free space at
the end of the partition for the LUKS header (which, I guess, makes it
a footer), so we need to resize the filesystem to leave room for that,
which is the trickiest bit.
This is a possibly destructive behavior. Be sure your backups are up
to date, or be ready to lose all data on the device.
We assume 512 byte sectors here. Check your sector size with fdisk
-l and adjust accordingly.
- Before you perform the procedure, make sure requirements are
installed:
apt install cryptsetup systemd-cryptsetup cryptsetup-initramfs
Note that this requires network access, of course.
- Reboot in a live image, I like GRML but any Debian live image
will work, possibly including the installer
- First, calculate how many sectors to free up for the LUKS header
qalc> 32Mibyte / ( 512 byte )
(32 mebibytes) / (512 bytes) = 65536
- Find the sector sizes of the Linux partitions:
fdisk -l /dev/nvme0n1 awk '/filesystem/ print $1 " " $4 '
For example, here's an example with a /boot and / filesystem:
$ sudo fdisk -l /dev/nvme0n1 awk '/filesystem/ print $1 " " $4 '
/dev/nvme0n1p2 999424
/dev/nvme0n1p3 3904979087
- Substract 1 from 2:
qalc> set precision 100
qalc> 3904979087 - 65536
Or, last step and this one, in one line:
fdisk -l /dev/nvme0n1 awk '/filesystem/ print $1 " " $4 - 65536 '
- Recheck filesystem:
e2fsck -f /dev/nvme0n1p2
- Resize filesystem:
resize2fs /dev/nvme0n1p2 $(fdisk -l /dev/nvme0n1 awk '/nvme0n1p2/ print $4 - 65536 ')s
Notice the trailing s here: it makes resize2fs interpret the
number as a 512 byte sector size, as opposed to the default (4k
blocks).
- Re-encrypt filesystem:
cryptsetup reencrypt --encrypt /dev/nvme0n1p2 --resize-device-size=32M
This is it! This is the most important step! Make sure your laptop
is plugged in and try not to interrupt it. This can, apparently,
be resumed without problem, but I'd hate to show you how.
This will show progress information like:
Progress: 2.4% ETA 23m45s, 53GiB written, speed 1.3 GiB/s
Wait until the ETA has passed.
- Open and mount the encrypted filesystem and mount the EFI system
partition (ESP):
cryptsetup open /dev/nvme0n1p2 crypt
mount /dev/mapper/crypt /mnt
mount /dev/nvme0n1p1 /mnt/boot/efi
If this fails, now is the time to consider restoring from backups.
- Enter the
chroot
for fs in proc sys dev ; do
mount --bind /$fs /mnt/$fs
done
chroot /mnt
Pro tip: this can be done in one step in GRML with:
grml-chroot /mnt bash
- Generate a
crypttab:
echo crypt_dev_nvme0n1p2 UUID=$(blkid -o value -s UUID /dev/nvme0n1p2) none luks,discard >> /etc/crypttab
- Adjust root filesystem in
/etc/fstab, make sure you have a line
like this:
/dev/mapper/crypt_dev-nvme0n1p2 / ext4 errors=remount-ro 0 1
If you were already using a UUID entry for this, there's nothing
to change!
- Configure the root filesystem in the
initrd:
echo root=/dev/mapper/crypt_dev_nvme0n1p2 > /etc/kernel/cmdline
- Regenerate UKI:
dpkg-reconfigure linux-image-$(uname -r)
Be careful here! systemd-boot inherits the command line from the
system where it is generated, so this will possibly feature some
unsupported commands from your boot environment. In my
case GRML had a couple of those, which broke the boot. It's still
possible to workaround this issue by tweaking the arguments at
boot time, that said.
- Exit chroot and reboot
exit
reboot
Some of the ideas in this section were taken from this guide but
was mostly rewritten to simplify the work. My guide also avoids the
grub hacks or a specific initrd system (as the guide uses
initramfs-tools and grub, while I, above, switched to dracut and
systemd-boot). RHEL also has a similar guide, perhaps even
better.
Somehow I have made this system without LVM at all,
which simplifies things a bit (as I don't need to also resize the
physical volume/volume groups), but if you have LVM, you need to tweak
this to also resize the LVM bits. The RHEL guide has some information
about this.
apt install cryptsetup systemd-cryptsetup cryptsetup-initramfs
Note that this requires network access, of course.qalc> 32Mibyte / ( 512 byte )
(32 mebibytes) / (512 bytes) = 65536
fdisk -l /dev/nvme0n1 awk '/filesystem/ print $1 " " $4 '
For example, here's an example with a /boot and / filesystem:
$ sudo fdisk -l /dev/nvme0n1 awk '/filesystem/ print $1 " " $4 '
/dev/nvme0n1p2 999424
/dev/nvme0n1p3 3904979087
qalc> set precision 100
qalc> 3904979087 - 65536
Or, last step and this one, in one line:
fdisk -l /dev/nvme0n1 awk '/filesystem/ print $1 " " $4 - 65536 '
e2fsck -f /dev/nvme0n1p2
resize2fs /dev/nvme0n1p2 $(fdisk -l /dev/nvme0n1 awk '/nvme0n1p2/ print $4 - 65536 ')s
Notice the trailing s here: it makes resize2fs interpret the
number as a 512 byte sector size, as opposed to the default (4k
blocks).cryptsetup reencrypt --encrypt /dev/nvme0n1p2 --resize-device-size=32M
This is it! This is the most important step! Make sure your laptop
is plugged in and try not to interrupt it. This can, apparently,
be resumed without problem, but I'd hate to show you how.
This will show progress information like:
Progress: 2.4% ETA 23m45s, 53GiB written, speed 1.3 GiB/s
Wait until the ETA has passed.cryptsetup open /dev/nvme0n1p2 crypt
mount /dev/mapper/crypt /mnt
mount /dev/nvme0n1p1 /mnt/boot/efi
If this fails, now is the time to consider restoring from backups.chroot
for fs in proc sys dev ; do
mount --bind /$fs /mnt/$fs
done
chroot /mnt
Pro tip: this can be done in one step in GRML with:
grml-chroot /mnt bash
crypttab:
echo crypt_dev_nvme0n1p2 UUID=$(blkid -o value -s UUID /dev/nvme0n1p2) none luks,discard >> /etc/crypttab
/etc/fstab, make sure you have a line
like this:
/dev/mapper/crypt_dev-nvme0n1p2 / ext4 errors=remount-ro 0 1
If you were already using a UUID entry for this, there's nothing
to change!initrd:
echo root=/dev/mapper/crypt_dev_nvme0n1p2 > /etc/kernel/cmdline
dpkg-reconfigure linux-image-$(uname -r)
Be careful here! systemd-boot inherits the command line from the
system where it is generated, so this will possibly feature some
unsupported commands from your boot environment. In my
case GRML had a couple of those, which broke the boot. It's still
possible to workaround this issue by tweaking the arguments at
boot time, that said.exit
reboot
Historically the primary way to contribute to Debian has been to email the Debian bug tracker with a code patch. Now that
Once forking is complete,
It may also be good to build the source package to establish a baseline of the current state and what kind of binaries and
When you see a new Merge Request, try to review it within a couple of days. If you cannot review in a reasonable time, posting a small note that you intend to review it later will feel better to the submitter compared to not getting any response.
Personally, I have a habit of assigning myself as a reviewer so that I can keep track of my whole review queue at
When adding the first comment, I choose Start review and for the following remarks Add to review. Finally, I click Finish review and Submit review, which will trigger one single email to the submitter with all my feedback. I try to avoid using the Add comment now option, as each such comment triggers a separate notification email to the submitter.
It appears that the fragile masculinity tech evangelists have identified Debian as a community with boundaries which exclude them from abusing its members and they re so angry about it! In response to posts such as
Like each month, have a look at the work funded by
People keep asking me when I ll write the next instalment of my local voice assistant journey. I didn t mean for it to be so long since the last one, things have been busier than I d like. Anyway. Last time we d
Debian 13 has finally 



















Introducing
About 90% of my Debian contributions this month were
As I m currently somewhat underemployed, and could do with some extra income, I m starting
There's a lovely device called a