Raspberry Pi LVM on LUKS: Difference between revisions

From Alpine Linux
(Add Caveats section)
(Remove the obsolete keydisk instructions (cryptkey on separate device is here!), and replace the section "Verify the Installation" with thorough configuration steps (as setup-disk won't always do it for us).)
Line 10: Line 10:


==Disk Setup==
==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.
# 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.
# Create a larger Linux partition (e.g. ''/dev/sdb2'') that will be LUKS-encrypted.


Install the necessary packages:
Install the necessary packages:
{{cmd|apk add cryptsetup lvm2}}
{{cmd|apk add cryptsetup lvm2 mkinitfs}}


Encrypt the Linux partition with one of the following:
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}}
{{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.
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}}
{{cmd|setup-disk -m sys /mnt}}


==Verify the Installation==
''setup-disk'' should setup most things for us, but it's a good idea to inspect the results before you reboot.


Here's a list of files to check:
==Configure Boot Settings==
* ''/mnt/etc/mkinitfs/mkinitfs.conf'' should have the features <code>lvm</code> and <code>cryptsetup</code>.
''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.
* ''/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>).
:1. Edit ''/mnt/etc/mkinitfs/mkinitfs.conf'' and add the features <code>lvm</code> and <code>cryptsetup</code>, if missing.
:2. Edit ''/mnt/boot/cmdline.txt'', and ensure that <code>root=</code> points to the respective LVM volume (e.g. ''/dev/alpine/root'').


==Optional: Decrypt with a Keydisk==
::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).
The "keydisk" — a storage device used as a decryption key — is a convenient method to enable full-disk encryption, especially for a headless server.
::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].


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.
:3. Edit ''/mnt/etc/fstab'' and verify that all LVM volumes and the ''/boot'' partition are listed there.


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.
::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>.


===Create the keyfile===
:4. [[Initramfs_init#Usage|Regenerate the initramfs]]. Remember to point it to the ''/mnt'' path.


Create an empty file and fix its permissions:
Finally, a friendly reminder: save a backup of that LUKS header. See [https://manned.org/man/cryptsetup-luksHeaderBackup cryptsetup-luksHeaderBackup(8)].
{{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>
===Caveats===
Always remember to plug in the keydisk before doing any upgrades. It's helpful to write a reminder in ''/etc/motd'':
<pre>
...
ALWAYS INSERT THE BOOT DISK BEFORE YOU UPGRADE OR REBOOT.
</pre>
It also means that '''you should not be automating upgrades'''.


==See also==
==See also==

Revision as of 20:58, 2 May 2026

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.

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.

  1. Initialize the disk with a new empty DOS partition table.
  2. Create a bootable FAT32 partition (as described here) that will later be mounted as the (unencrypted) /boot filesystem (e.g. /dev/sdb1).
  3. 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


Configure Boot Settings

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).


See also

Retrieved from "https://wiki.alpinelinux.org/w/index.php?title=Raspberry_Pi_LVM_on_LUKS&oldid=32372"