Setting up ZFS on LUKS - Revision history

Prabuanand: added and modified link

2025-04-02T10:10:34Z

added and modified link

← Older revision		Revision as of 10:10, 2 April 2025
Line 1:		Line 1:
	This page describes how to set up Alpine Linux using ZFS with a pool that is located in an encrypted partition. To encrypt the partition the Device Mapper crypt (dm-crypt) module and Linux Unified Key Setup (LUKS) is used.		This page describes how to set up Alpine Linux using [[ZFS]] with a pool that is located in an encrypted partition. To encrypt the partition the Device Mapper crypt (dm-crypt) module and Linux Unified Key Setup (LUKS) is used.

	Note that you must install the <code>/boot/</code> directory on an unecrypted partition to boot correctly. This page is based on the syslinux bootloader and traditional BIOS booting.		Note that you must install the <code>/boot/</code> directory on an unecrypted partition to boot correctly. This page is based on the syslinux bootloader and traditional BIOS booting.
Line 257:		Line 257:

	* [https://openzfs.github.io/openzfs-docs/Getting%20Started/Alpine%20Linux/Root%20on%20ZFS.html Root on ZFS guide with native encryption]		* [https://openzfs.github.io/openzfs-docs/Getting%20Started/Alpine%20Linux/Root%20on%20ZFS.html Root on ZFS guide with native encryption]
	* [[~~Setting up~~ ZFS with ~~native encryption\|Setting~~ up ZFS with native encryption]]		* [[ZFS\|Main ZFS page with instructions for up ZFS with native encryption]]
	* [[Root on ZFS with native encryption\| Root on ZFS guide with native encryption]]		* [[Root on ZFS with native encryption\| Root on ZFS guide with native encryption]]
	* [[Setting up encrypted volumes with LUKS]]		* [[Setting up encrypted volumes with LUKS]]

Prabuanand: added category installation

2025-04-02T07:45:10Z

added category installation

← Older revision		Revision as of 07:45, 2 April 2025
Line 261:		Line 261:
	* [[Setting up encrypted volumes with LUKS]]		* [[Setting up encrypted volumes with LUKS]]
	[[Category:Storage]]		[[Category:Storage]]
			[[Category:Installation]]
	[[Category:Security]]		[[Category:Security]]

Prabuanand: fixed up the heading levels and changed the introduction paragraph.added internal links

2025-03-26T13:38:16Z

fixed up the heading levels and changed the introduction paragraph.added internal links

← Older revision		Revision as of 13:38, 26 March 2025
Line 1:		Line 1:
	~~= Native Encryption =~~		This page describes how to set up Alpine Linux using ZFS with a pool that is located in an encrypted partition. To encrypt the partition the Device Mapper crypt (dm-crypt) module and Linux Unified Key Setup (LUKS) is used.

	~~ZFS now has native support for encryption~~. This ~~has many advantages over ZFS~~ on ~~LUKS including multi-disk, encrypted zfs send, portable across *BSD/Linux~~ and ~~others~~.		Note that you must install the <code>/boot/</code> directory on an unecrypted partition to boot correctly. This page is based on the syslinux bootloader and traditional BIOS booting.

	~~For a Root on~~ ZFS ~~guide~~ with native encryption~~, see [https://openzfs.github.io/openzfs-docs/Getting%20Started/Alpine%20Linux/Root%20on%20ZFS.html here~~].		ZFS now has [[Setting up ZFS with native encryption\|native support for encryption]]. This has many advantages over ZFS on LUKS including multi-disk, encrypted zfs send, portable across *BSD/Linux and others.

	~~= Introduction =~~

	This ~~documentation describes how to set up Alpine Linux using~~ ZFS ~~with a pool that is located in an~~ encrypted ~~partition. To encrypt the partition the Device Mapper crypt (dm-crypt) module and~~ Linux ~~Unified Key Setup (LUKS) is used.~~

	~~Note that you must install the <code>/boot/</code> directory on an unecrypted partition to boot correctly.~~

	~~We'll be using the syslinux bootloader~~ and ~~traditional BIOS booting~~.

	== Requirements ==		== Requirements ==

	* An instance Alpine on a medium other than the one you'll boot from, see [[Installation\|official installation guide.]]		An instance Alpine on a medium other than the one you'll boot from, see [[Installation\|official installation guide.]]
	{{Note\|We can't use the live environment from the installation isos, because we'll install the ZFS kernel module and that isn't possible with a read-only /boot (as provided by the iso).}}		{{Note\|We can't use the live environment from the installation isos, because we'll install the ZFS kernel module and that isn't possible with a read-only /boot (as provided by the iso).}}

	=~~= Hard Disk Device Name ==~~		== Setting up Alpine Linux Using ZFS on Top of a LUKS Partition ==

	The following documentation uses the <code>/dev/sda</code> device as the installation destination. If your environment uses a different device name for your hard disk, use the corresponding device name in the examples.

	= Setting up Alpine Linux Using ZFS on Top of a LUKS Partition =

	To install Alpine Linux in a ZFS pool on top of a LUKS encrypted partition, you cannot use the [[Installation\|official installation]] procedure. The installation requires several manual steps you must run in the Alpine Linux Live CD environment.		To install Alpine Linux in a ZFS pool on top of a LUKS encrypted partition, you cannot use the [[Installation\|official installation]] procedure. The installation requires several manual steps you must run in the Alpine Linux Live CD environment.

	== Preparing the Installation Environment ==		=== Preparing the Installation Environment ===

	Before you begin to install Alpine Linux on the medium you intend to boot from, prepare the installation you already have:		Before you begin to install Alpine Linux on the medium you intend to boot from, prepare the installation you already have:
Line 39:		Line 27:
	# modprobe zfs		# modprobe zfs

	== Creating the Partition Layout ==		=== Creating the Partition Layout ===

	Linux requires an unencrypted <code>/boot/</code> partition to boot. You can assign the remaining space for the encrypted ZFS pool.		Linux requires an unencrypted <code>/boot/</code> partition to boot. You can assign the remaining space for the encrypted ZFS pool.

			{{Note\|Instructions on this page uses {{path\|'''/dev/sda'''}} as storage device name. If your environment uses a different device name for your hard disk, use the corresponding device name in the examples. To find your storage device's name, you could either use the <code>lsblk</code> command from the {{pkg\|util-linux}} package or you could make an educated guess by using BusyBox's <code>blkid</code> and <code>df</code> commands.}}

	* Start the <code>fdisk</code> utility to set up partitions:		* Start the <code>fdisk</code> utility to set up partitions:
Line 70:		Line 60:
	{{Note\|Depending on the size of the partition, this process can take from several minutes to many hours.}}		{{Note\|Depending on the size of the partition, this process can take from several minutes to many hours.}}

	== Encrypting the ZFS Partition ==		=== Encrypting the ZFS Partition ===

	* To encrypt the partition which will later contain the LVM PV:		* To encrypt the partition which will later contain the LVM PV:
Line 88:		Line 78:
	Consult <code>cryptsetup --help</code> for options.		Consult <code>cryptsetup --help</code> for options.

	== Creating the filesystems ==		=== Creating the filesystems ===

	* Open the LUKS partition:		* Open the LUKS partition:
Line 94:		Line 84:
	# cryptsetup open --type luks /dev/sda2 crypt		# cryptsetup open --type luks /dev/sda2 crypt

	=== Creating the ZFS pool ===		==== Creating the ZFS pool ====

	# zpool create -o ashift=12 -O normalization=formD -O atime=off -m none -R /mnt -O compression=lz4 tank /dev/mapper/crypt		# zpool create -o ashift=12 -O normalization=formD -O atime=off -m none -R /mnt -O compression=lz4 tank /dev/mapper/crypt
Line 151:		Line 141:
	</pre>		</pre>

	=== Creating the required datasets ===		==== Creating the required datasets ====

	# zfs create -o mountpoint=none -o canmount=off tank/ROOT		# zfs create -o mountpoint=none -o canmount=off tank/ROOT
	# zfs create -o mountpoint=/ tank/ROOT/alpine		# zfs create -o mountpoint=/ tank/ROOT/alpine

	=== Creating optional datasets (feel free to add your own) ===		==== Creating optional datasets (feel free to add your own) ====

	# zfs create -o mountpoint=/home tank/HOME		# zfs create -o mountpoint=/home tank/HOME
	# zfs create -o mountpoint=/var/log tank/LOG		# zfs create -o mountpoint=/var/log tank/LOG

	== Creating the <code>/boot</code> filesystem ==		=== Creating the <code>/boot</code> filesystem ===

	# mkfs.ext4 /dev/sda1		# mkfs.ext4 /dev/sda1

	== Mounting the <code>/boot</code> filesystem ==		=== Mounting the <code>/boot</code> filesystem ===

	* Create <code>/mnt/boot/</code> directory and mount the <code>/dev/sda1</code> partition in this directory:		* Create <code>/mnt/boot/</code> directory and mount the <code>/dev/sda1</code> partition in this directory:
Line 172:		Line 162:
	# mount -t ext4 /dev/sda1 /mnt/boot/		# mount -t ext4 /dev/sda1 /mnt/boot/

	== Installing Alpine Linux ==		=== Installing Alpine Linux ===

	In this step you will install Alpine Linux in the <code>/mnt/</code> directory, which contains the mounted file system structure.		In this step you will install Alpine Linux in the <code>/mnt/</code> directory, which contains the mounted file system structure.
Line 221:		Line 211:
	# dd bs=440 count=1 conv=notrunc if=/mnt/usr/share/syslinux/mbr.bin of=/dev/sda		# dd bs=440 count=1 conv=notrunc if=/mnt/usr/share/syslinux/mbr.bin of=/dev/sda

	== Unmounting the filesystems ==		=== Unmounting the filesystems ===

	* Unmount <code>/mnt/boot/</code>:		* Unmount <code>/mnt/boot/</code>:
Line 243:		Line 233:
	# reboot		# reboot

	= Troubleshooting =		== Troubleshooting ==

	== General Procedure ==		=== General Procedure ===

	In case your system fails to boot, you can verify the settings and fix incorrect configurations:		In case your system fails to boot, you can verify the settings and fix incorrect configurations:
Line 264:		Line 254:
	* [[#Unmounting_the_Volumes_and_Partitions\|Unmount the volumes and partitions]]		* [[#Unmounting_the_Volumes_and_Partitions\|Unmount the volumes and partitions]]

	~~{{Todo\|Multiple Disk ZFS on LUKS?}}~~		==See also==

			* [https://openzfs.github.io/openzfs-docs/Getting%20Started/Alpine%20Linux/Root%20on%20ZFS.html Root on ZFS guide with native encryption]
			* [[Setting up ZFS with native encryption\|Setting up ZFS with native encryption]]
			* [[Root on ZFS with native encryption\| Root on ZFS guide with native encryption]]
			* [[Setting up encrypted volumes with LUKS]]
	[[Category:Storage]]		[[Category:Storage]]
	[[Category:Security]]		[[Category:Security]]

Zcrayfish: /* Native Encryption */ Rescued dead link.

2023-08-26T05:46:52Z

Native Encryption: Rescued dead link.

← Older revision		Revision as of 05:46, 26 August 2023
Line 3:		Line 3:
	ZFS now has native support for encryption. This has many advantages over ZFS on LUKS including multi-disk, encrypted zfs send, portable across *BSD/Linux and others.		ZFS now has native support for encryption. This has many advantages over ZFS on LUKS including multi-disk, encrypted zfs send, portable across *BSD/Linux and others.

	For a Root on ZFS guide with native encryption, see [https://openzfs.github.io/openzfs-docs/Getting%20Started/Alpine%20Linux/Root%20on%20ZFS~~/1-preparation~~.html here].		For a Root on ZFS guide with native encryption, see [https://openzfs.github.io/openzfs-docs/Getting%20Started/Alpine%20Linux/Root%20on%20ZFS.html here].

	= Introduction =		= Introduction =

Psykose: haveged is not useful on modern kernels

2023-04-29T02:11:27Z

haveged is not useful on modern kernels

← Older revision		Revision as of 02:11, 29 April 2023
Line 36:		Line 36:
	* Install the following packages required to set up ZFS and LUKS:		* Install the following packages required to set up ZFS and LUKS:

	# apk add ~~haveged~~ cryptsetup e2fsprogs syslinux zfs zfs-$(uname -r \| rev \| cut -d'-' -f1 \| rev)		# apk add cryptsetup e2fsprogs syslinux zfs zfs-$(uname -r \| rev \| cut -d'-' -f1 \| rev)
	# modprobe zfs		# modprobe zfs

	* Optionally, start the <code>haveged</code> service for unpredictable random numbers used for encryption:

	~~# rc-service haveged start~~

	== Creating the Partition Layout ==		== Creating the Partition Layout ==
Line 70:		Line 66:
	* Optionally, fill the LUKS partition with random values:		* Optionally, fill the LUKS partition with random values:

	# ~~haveged -n 0 \|~~ dd of=/dev/sda2		# dd if=/dev/urandom of=/dev/sda2 bs=1M

	{{Note\|Depending on the size of the partition, this process can take from several minutes to many hours.}}		{{Note\|Depending on the size of the partition, this process can take from several minutes to many hours.}}

Psykose: urandom, show defaults for cryptsetup

2023-01-10T09:01:34Z

urandom, show defaults for cryptsetup

← Older revision		Revision as of 09:01, 10 January 2023
Line 88:		Line 88:
	:* To encrypt the partition using individual settings, enter, for example:		:* To encrypt the partition using individual settings, enter, for example:

	# cryptsetup -v -c ~~serpent~~-xts-plain64 -s ~~512~~ --hash ~~sha512~~ --iter-time ~~5000~~ --use-~~random~~ luksFormat /dev/sda2		# cryptsetup -v -c aes-xts-plain64 -s 256 --hash sha256 --iter-time 2000 --use-urandom luksFormat /dev/sda2

			Consult <code>cryptsetup --help</code> for options.

	== Creating the filesystems ==		== Creating the filesystems ==

Mmhiro: whirlpool is a legacy hash in OpenSSL 3.0, used in Alpine 3.17. This breaks decryption in initramfs.

2022-12-02T07:26:24Z

whirlpool is a legacy hash in OpenSSL 3.0, used in Alpine 3.17. This breaks decryption in initramfs.

← Older revision		Revision as of 07:26, 2 December 2022
Line 88:		Line 88:
	:* To encrypt the partition using individual settings, enter, for example:		:* To encrypt the partition using individual settings, enter, for example:

	# cryptsetup -v -c serpent-xts-plain64 -s 512 --hash ~~whirlpool~~ --iter-time 5000 --use-random luksFormat /dev/sda2		# cryptsetup -v -c serpent-xts-plain64 -s 512 --hash sha512 --iter-time 5000 --use-random luksFormat /dev/sda2

	== Creating the filesystems ==		== Creating the filesystems ==

La9: native encryption

2022-07-27T14:27:07Z

native encryption

← Older revision		Revision as of 14:27, 27 July 2022
Line 1:		Line 1:
			= Native Encryption =

			ZFS now has native support for encryption. This has many advantages over ZFS on LUKS including multi-disk, encrypted zfs send, portable across *BSD/Linux and others.

			For a Root on ZFS guide with native encryption, see [https://openzfs.github.io/openzfs-docs/Getting%20Started/Alpine%20Linux/Root%20on%20ZFS/1-preparation.html here].

	= Introduction =		= Introduction =

Bt129: /* Installing Alpine Linux */

2021-07-05T04:21:45Z

Installing Alpine Linux

← Older revision		Revision as of 04:21, 5 July 2021
Line 178:		Line 178:
	: The installer downloads the latest packages to install the base installation. Additionally, the installer automatically creates the entries for the mount points in the <code>fstab</code> file (but we'll have to edit it manually later), which are currently mounted in the <code>/mnt/</code> directory.		: The installer downloads the latest packages to install the base installation. Additionally, the installer automatically creates the entries for the mount points in the <code>fstab</code> file (but we'll have to edit it manually later), which are currently mounted in the <code>/mnt/</code> directory.

	: {{Note\|The automatic writing of the master boot record (MBR) fails in this step. ~~You will~~ write the MBR ~~later manually~~ to the disk.}}		: {{Note\|The automatic writing of the master boot record (MBR) fails in this step. Later, you'll write the MBR to the disk manually.}}

	* To enable the operating system to decrypt the LUKS partition at boot time, create the <code>/mnt/etc/crypttab</code> file. Enter the following line into the file to decrypt the <code>/dev/sda2</code> partition using the <code>luks</code> module and map it to the <code>lvmcrypt</code> name:		* To enable the operating system to decrypt the LUKS partition at boot time, create the <code>/mnt/etc/crypttab</code> file. Enter the following line into the file to decrypt the <code>/dev/sda2</code> partition using the <code>luks</code> module and map it to the <code>lvmcrypt</code> name:
Line 184:		Line 184:
	crypt /dev/sda2 none luks		crypt /dev/sda2 none luks

	* Delete the zfs entries in <code>/mnt/etc/fstab</code> as ZFS mounts them automagically~~, your~~ fstab should look ~~like~~ this:		* Delete the zfs entries in <code>/mnt/etc/fstab</code> as ZFS mounts them automagically. Your fstab should look similar to this:

	UUID=6b4f2c9c-0a0f-4a8c-a73b-d2b47920ad6f /boot ext4 rw,relatime,stripe=4,data=ordered 0 2		UUID=6b4f2c9c-0a0f-4a8c-a73b-d2b47920ad6f /boot ext4 rw,relatime,stripe=4,data=ordered 0 2
Line 205:		Line 205:
	: The <code>cryptroot</code> parameter sets the name of the device that contains the root file system. The <code>cryptdm</code> parameter sets the name of the mapping previously set in the <code>crypttab</code> file. The <code>rootfstype</code> option sets the root filesystem type to zfs.		: The <code>cryptroot</code> parameter sets the name of the device that contains the root file system. The <code>cryptdm</code> parameter sets the name of the mapping previously set in the <code>crypttab</code> file. The <code>rootfstype</code> option sets the root filesystem type to zfs.

	* Because the <code>update-extlinux</code> utility ~~operators~~ only on the <code>/boot/</code> directory, temporarily change the root to the <code>/mnt/</code> directory and update the boot loader configuration:		* Because the <code>update-extlinux</code> utility operates only on the <code>/boot/</code> directory, temporarily change the root to the <code>/mnt/</code> directory and update the boot loader configuration:

	# chroot /mnt/		# chroot /mnt/

Bt129: /* Creating the Partition Layout */

2021-07-04T18:12:23Z

Creating the Partition Layout

← Older revision		Revision as of 18:12, 4 July 2021
Line 52:		Line 52:

	:* Create the LUKS partition:		:* Create the LUKS partition:
	::* Enter <code>n</code> → <code>p</code> → <code>2</code> to start creating the next partition. Press <code>Enter</code> to select the default start cylinder. Enter the size ~~of partition~~. For example, <code>512m</code> for 512 MB or <code>5g</code> for 5 GB. Alternatively press <code>Enter</code> to set the maximum available size.		::* Enter <code>n</code> → <code>p</code> → <code>2</code> to start creating the next partition. Press <code>Enter</code> to select the default start cylinder. Enter the partition size. For example, <code>512m</code> for 512 MB or <code>5g</code> for 5 GB. Alternatively, press <code>Enter</code> to set the maximum available size.

	:* To verify the settings, press <code>p</code>. The output ~~shows, for example~~:		:* To verify the settings, press <code>p</code>. The output should look similar to this:
	<pre>		<pre>
	Device Boot Start End Sectors Size Id Type		Device Boot Start End Sectors Size Id Type
Line 62:		Line 62:
	* Press <code>w</code> to save the changes.		* Press <code>w</code> to save the changes.

	* Optionally, ~~wipe~~ the LUKS partition with random values:		* Optionally, fill the LUKS partition with random values:

	# haveged -n 0 \| dd of=/dev/sda2		# haveged -n 0 \| dd of=/dev/sda2

	{{Note\|Depending on the size of the partition, this process can take several minutes to hours.}}		{{Note\|Depending on the size of the partition, this process can take from several minutes to many hours.}}

	== Encrypting the ZFS Partition ==		== Encrypting the ZFS Partition ==