Raspberry Pi LVM on LUKS: Difference between revisions

Latest revision as of 21:27, 2 May 2026

This article complements the existing installation instructions for Raspberry Pi, providing the needed changes that enable booting with an encrypted disk.

Prepare the Installation Media

Write the downloaded image or tarball to a disk. In this example, this bootable disk (referred to as /dev/sda) will be used as a read-only installation media. The target root disk is referred to as /dev/sdb.

Boot the Installer

Insert the installation disk into the pi and turn it on. To make sure it will boot the right device, unplug any other storage media.

Once Alpine is initialized, log in and perform a "diskless installation" with setup-alpine. Next, we will setup the disk manually.

Disk Setup

Plug in the disk where Alpine will be installed. fdisk -l and blkid should give you an overview of all available disks. In this example, the new disk becomes /dev/sdb.

Initialize the disk with a new empty DOS partition table.
Create a bootable FAT32 partition (as described here) that will later be mounted as the (unencrypted) /boot filesystem (e.g. /dev/sdb1).
Create a larger Linux partition (e.g. /dev/sdb2) that will be LUKS-encrypted.

Install the necessary packages:

apk add cryptsetup lvm2 mkinitfs

Encrypt the Linux partition with one of the following:

cryptsetup luksFormat /dev/sdb2 # Raspberry Pi 5

cryptsetup luksFormat -c xchacha12,aes-adiantum-plain64 /dev/sdb2 # Raspberry Pi 4 and older

Then unlock the disk with cryptsetup open /dev/sdb2 alpine, where "alpine" is a name of choice.

At this point you may follow the LVM on LUKS page to create and format the LVM volumes.

Mount the root volume at /mnt, and the boot partition at /mnt/boot; then run setup-disk like this:

setup-disk -m sys /mnt

Boot Configuration

setup-disk should have installed the system to the target disk. Now we just need to verify a few things so it's ready to boot.

1. Edit /mnt/etc/mkinitfs/mkinitfs.conf and add the features lvm and cryptsetup, if missing.

2. Edit /mnt/boot/cmdline.txt, and ensure that root= points to the respective LVM volume (e.g. /dev/alpine/root).

In the same file, add cryptroot=UUID= pointing to the LUKS device (e.g. /dev/sdb2, but as UUID), and also cryptdm= set to a name of choice (e.g. alpine).

These options are documented here and here.

3. Edit /mnt/etc/fstab and verify that all LVM volumes and the /boot partition are listed there.

Add a line for the swap volume too. There's an example here.

If your disk is an ordinary flash stick or SD card, you might want to replace all instances of relatime with noatime.

4. Regenerate the initramfs. Remember to point it to the /mnt path.

Finally, a friendly reminder: save a backup of that LUKS header. See cryptsetup-luksHeaderBackup(8).

@@ Line 1: / Line 1: @@
-Installing Alpine on an encrypted root article complements the existing installation instructions for Raspberry Pi, providing only the needed changes that enable booting from an encrypted media. Use it only as a reference, not as a complete walk-through for installation.
+This article complements the existing installation instructions for Raspberry Pi, providing the needed changes that enable booting with an encrypted disk.
 ==Prepare the Installation Media==
@@ Line 10: / Line 10: @@
 ==Disk Setup==
-Plug in the disk to be used as the encrypted root. <code>fdisk -l</code> and <code>blkid</code> should give you an overview of all available disks. In this example, the new disk becomes ''/dev/sdb''.
+Plug in the disk where Alpine will be installed. <code>fdisk -l</code> and <code>blkid</code> should give you an overview of all available disks. In this example, the new disk becomes ''/dev/sdb''.
 # Initialize the disk with a new empty DOS partition table.
-# Create a bootable FAT32 partition ([[Raspberry_Pi#Manual_method|as described here]]) that will later be mounted as the (unencrypted) ''/boot'' filesystem. Important: if you plan to [[Raspberry_Pi_LVM_on_LUKS#Optional:_Decrypt_with_a_Keydisk|decrypt with a keydisk]], create the ''/boot'' partition on that disk instead.
+# Create a bootable FAT32 partition ([[Raspberry_Pi#Manual_method|as described here]]) that will later be mounted as the (unencrypted) ''/boot'' filesystem (e.g. ''/dev/sdb1'').
 # Create a larger Linux partition (e.g. ''/dev/sdb2'') that will be LUKS-encrypted.
 Install the necessary packages:
-{{cmd|apk add cryptsetup lvm2}}
+{{cmd|apk add cryptsetup lvm2 mkinitfs}}
 Encrypt the Linux partition with one of the following:
@@ Line 23: / Line 23: @@
 {{cmd|cryptsetup luksFormat -c xchacha12,aes-adiantum-plain64 /dev/sdb2    # Raspberry Pi 4 and older}}
-Then unlock the disk with <code>cryptsetup open /dev/sdb2 alpine</code>
+Then unlock the disk with <code>cryptsetup open /dev/sdb2 alpine</code>, where "alpine" is a name of choice.
 At this point you may follow the [[LVM_on_LUKS#Creating_the_Logical_Volumes_and_File_Systems|LVM on LUKS page]] to create and format the LVM volumes.
@@ Line 30: / Line 30: @@
 {{cmd|setup-disk -m sys /mnt}}
-==Verify the Installation==
+==Boot Configuration==
-''setup-disk'' should setup most things for us, but it's a good idea to inspect the results before you reboot.
+''setup-disk'' should have installed the system to the target disk. Now we just need to verify a few things so it's ready to boot.
-Here's a list of files to check:
+:1. Edit ''/mnt/etc/mkinitfs/mkinitfs.conf'' and add the features <code>lvm</code> and <code>cryptsetup</code>, if missing.
-* ''/mnt/etc/mkinitfs/mkinitfs.conf'' should have the features <code>lvm</code> and <code>cryptsetup</code>.
+:2. Edit ''/mnt/boot/cmdline.txt'', and ensure that <code>root=</code> points to the respective LVM volume (e.g. ''/dev/alpine/root'').
-* ''/mnt/boot/cmdline.txt'' should contain the following options: <code>root=/dev/vg0/root cryptroot=UUID=<LUKS_DEVICE_UUID> cryptdm=alpine</code>
-* ''/mnt/etc/fstab'' should have a line for <code>/dev/vg0/root</code> (and any other LVM volumes), and <code>/boot</code> (by UUID).
-Finally, a friendly reminder: save a backup of that LUKS header (see <code>cryptsetup-luksHeaderBackup(8)</code>).
+::In the same file, add <code>cryptroot=UUID=</code> pointing to the LUKS device (e.g. ''/dev/sdb2'', but as UUID), and also <code>cryptdm=</code> set to a name of choice (e.g. alpine).
+::These options are documented [[Setting_up_encrypted_volumes_with_LUKS#mkinitfs_and_LUKS|here]] and [https://manned.org/man/alpine-3.23/mkinitfs-bootparam.7 here].
-==Optional: Decrypt with a Keydisk==
+:3. Edit ''/mnt/etc/fstab'' and verify that all LVM volumes and the ''/boot'' partition are listed there.
-The "keydisk" — a storage device used as a decryption key — is a convenient method to enable full-disk encryption, especially for a headless server.
-Unfortunately, ''mkinitfs'' does not yet provide a way to specify the decryption keyfile on an external device, but there is a [https://gitlab.alpinelinux.org/alpine/mkinitfs/-/merge_requests/108 pending merge request] to add the functionality, as well as a workaround: '''move the entire ''/boot'' filesystem onto another device.''' That is what we will be doing.
+::Add a line for the swap volume too. There's an example [[LVM_on_LUKS#Installing_Alpine_Linux|here]].
+::If your disk is an ordinary flash stick or SD card, you might want to replace all instances of <code>relatime</code> with <code>noatime</code>.
-This assumes you've already booted a passphrase-encrypted Alpine installation, but with some adjustments you should be able to include this as part of the installation procedure.
+:4. [[Initramfs_init#Usage|Regenerate the initramfs]]. Remember to point it to the ''/mnt'' path.
-===Create the keyfile===
+Finally, a friendly reminder: save a backup of that LUKS header. See [https://manned.org/man/cryptsetup-luksHeaderBackup cryptsetup-luksHeaderBackup(8)].
-Create an empty file and fix its permissions:
-{{cmd|touch /crypto_keyfile.bin}}
-{{cmd|chmod 600 /crypto_keyfile.bin}}
-Use ''dd'' to fill it with random data:
-{{cmd|dd if{{=}}/dev/urandom of{{=}}/crypto_keyfile.bin bs{{=}}512 count{{=}}1}}
-Add the keyfile to the LUKS header:
-{{cmd|cryptsetup luksAddKey /dev/sdb2 /crypto_keyfile.bin}}
-===Prepare the Initramfs===
-The root disk decryption takes place in a temporary environment named [[Initramfs_init|initramfs]]. Once we generate it, the keyfile we created earlier will be copied into the initram filesystem, which sits inside the ''/boot'' disk. Because this disk is separated from the rest of the system, it can function as a decryption key — the system won't boot without it.
-The default path for the keyfile is <code>/crypto_keyfile.bin</code>, but you can change it by editing <code>/etc/mkinitfs/features.d/cryptkey.files</code>.
-It must also be passed as a kernel command-line option in <code>/boot/cmdline.txt</code>:
-<pre>
-cryptkey=/crypto_keyfile.bin
-</pre>
-Enable the necessary features in <code>/etc/mkinitfs/mkinitfs.conf</code>:
-<pre>
-features="... cryptsetup cryptkey"
-</pre>
-Regenerate the [[Initramfs_init#Usage|initramfs]]:
-<pre>
-mkinitfs -c /etc/mkinitfs/mkinitfs.conf -b /
-</pre>
 ==See also==
 * [[Raspberry Pi|Raspberry Pi]]
-* [[LVM_on_LUKS|LVM on LUKS]] ''(encryption and LVM, but beware not everything applies to the Pi)''
+* [[Setting_up_encrypted_volumes_with_LUKS|LUKS-encrypted volume setup]]
+* [[LVM_on_LUKS|LVM on LUKS]] ''(encryption and LVM, but beware that the Pi uses a different bootloader)''
+* [[Initramfs_init|Initramfs]]
 [[Category:Storage]]
 [[Category:Security]]
 [[Category:Raspberry]]