Setting up encrypted volumes with LUKS

2025-03-11T22:08:56Z

Juan: Add note about how to decrypt a volume before mounting via fstab

[https://en.wikipedia.org/wiki/Linux%20Unified%20Key%20Setup LUKS] allows encrypting a partition and mapping it as a virtual block device, which can then be used as a normal partition. Guides for other Linux distributions should serve as a general references for installing Alpine onto a LUKS encrypted disk.

The installer has built-in support for encryption. The default installer will not encrypt the swap partition and the boot partition. To setup Alpine Linux with an encrypted swap partition, refer to [[LVM on LUKS]]. The GRUB bootloader supports BIOS and EFI boot with an encrypted boot partition.

== Decrypting non-root volumes during boot ==

Differently to other Linux distributions, Alpine does not use the file <code>/etc/crypttab</code>. Instead, to have an encrypted volume be decrypted prior to automatically mounting it somewhere via <code>/etc/fstab</code>, you must configure <code>dmcrypt</code> in <code>/etc/conf.d/dmcrypt</code>. The comments inside that file should guide you, but as a simple example, here's what you should include in that file to decrypt and map a partition to some volume named, say, “<code>myvolume</code>”, given its UUID (here represented using a series of <code>X</code>s), using a passphrase:

<pre>
target=myvolume
source=UUID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX
</pre>

In <code>/etc/fstab</code>, then, you would include the following line:

<pre>
/dev/mapper/myvolume <path> <fstype> <options>
</pre>

substituting in the proper parameters.

== mkinitfs and LUKS ==

For those familiar with setting up FDE on other Linux distributions, this section contains only Alpine-specific knowledge required is understanding [[mkinitfs]].

First of all, the <code>cryptsetup</code> feature needs to be added to {{path|/etc/mkinitfs/mkinitfs.conf}}. Additionally, the following kernel parameters are required:

* <code>cryptroot</code> kernel parameter should point to the encrypted block device.
* <code>cryptdm</code>: the name that will be given to the device.
* <code>root</code> kernel parameter should point to the mapped block device: <code>/dev/mapper/<name used in cryptdm></code>.
* <code>rootfstype</code>: the filesystem type of the root partition (e.g.: <code>btrfs</code>).

For example if you use grub with GPT partition table, no LVM and ext4 you will have in {{path|/etc/default/grub}}:
<pre>
GRUB_TIMEOUT=2
GRUB_DISABLE_SUBMENU=y
GRUB_DISABLE_RECOVERY=true
GRUB_CMDLINE_LINUX_DEFAULT="modules=sd-mod,usb-storage,ext4 quiet rootfstype=ext4 cryptroot=UUID=a7dc90c4-6746-417e-b25b-cb8769ee6334 cryptdm=alpine-rootfs root=/dev/mapper/alpine-rootfs"
GRUB_PRELOAD_MODULES="luks cryptodisk part_gpt"
GRUB_ENABLE_CRYPTODISK=y
</pre>

== See also ==

* [[LVM on LUKS]]
* [[mkinitfs|Initramfs init]]
* [[Full disk encryption secure boot]]
* [https://wiki.archlinux.org/index.php/Dm-crypt dm-crypt on ArchWiki]

[[Category:Storage]]
[[Category:Security]]

Alpine Linux - User contributions [en]

Setting up encrypted volumes with LUKS