Root on ZFS with native encryption - Revision history

Prabuanand: added additional categories

2025-04-02T10:12:06Z

added additional categories

← Older revision		Revision as of 10:12, 2 April 2025
Line 104:		Line 104:
	* [https://openzfs.github.io/openzfs-docs/Getting%20Started/Alpine%20Linux/Root%20on%20ZFS.html OpenZFS Guide for Alpine Linux]		* [https://openzfs.github.io/openzfs-docs/Getting%20Started/Alpine%20Linux/Root%20on%20ZFS.html OpenZFS Guide for Alpine Linux]

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

Prabuanand: changed the category to Installation

2025-04-02T07:41:06Z

changed the category to Installation

← Older revision		Revision as of 07:41, 2 April 2025
Line 103:		Line 103:
	* [[ZFS]]		* [[ZFS]]
	* [https://openzfs.github.io/openzfs-docs/Getting%20Started/Alpine%20Linux/Root%20on%20ZFS.html OpenZFS Guide for Alpine Linux]		* [https://openzfs.github.io/openzfs-docs/Getting%20Started/Alpine%20Linux/Root%20on%20ZFS.html OpenZFS Guide for Alpine Linux]
	[[Category:~~Filesystems~~]]
			[[Category:Installation]]

Prabuanand: added category and links, fixed heading levels

2025-04-02T07:38:07Z

added category and links, fixed heading levels

← Older revision		Revision as of 07:38, 2 April 2025
Line 1:		Line 1:
	This is a guide for installing Alpine Linux with its root partition on an encrypted ZFS volume, using ZFS's own encryption capabilities. The system will be encrypted when powered off and will need to be unlocked by typing a passphrase at boot. To be able to boot the system, the `/boot` partition remains unencrypted.		This is a guide for installing Alpine Linux with its root partition on an encrypted [[ZFS]] volume, using ZFS's own encryption capabilities. The system will be encrypted when powered off and will need to be unlocked by typing a passphrase at boot. To be able to boot the system, the `/boot` partition remains unencrypted.

	= ~~OpenZFS Guide~~ =		== Initial Setup ==

	~~A guide on OpenZFS website supports native encryption, UEFI boot and legacy boot, and multi-disk. See [~~https://~~openzfs~~.~~github~~.io/~~openzfs~~-~~docs/Getting%20Started/Alpine%20Linux/Root%20on%20ZFS~~.~~html here]~~.		Download the '''extended''' release from https://www.alpinelinux.org/downloads/ as only it contains the zfs kernel modules the time of writing.as on (2022-02-12). Write it to a USB device and boot from it.

	~~= Downloading Alpine =~~		Run the following to start the installation procedure: {{cmd\|setup-alpine}}

	~~Download the '''extended''' release from https://www.alpinelinux.org/downloads/ as only it contains the zfs kernel modules at the time of writing (2022-02-12).~~

	~~Write it to a USB device and boot from it.~~

	~~= Initial Setup =~~

	Run the following to start the installation procedure:

	{{cmd\|setup-alpine}}

	Answer all the questions, and hit {{Key\|Ctrl}}+{{Key\|C}} when prompted for which disk you'd like to use.		Answer all the questions, and hit {{Key\|Ctrl}}+{{Key\|C}} when prompted for which disk you'd like to use.

	== Optional: SSH access ==		=== Optional: SSH access ===

	This section is optional and it assumes internet connectivity. You may enable sshd so you can ssh into the box and copy and paste the rest of the commands from these instructions into a terminal window.		This section is optional and it assumes internet connectivity. You may enable sshd so you can ssh into the box and copy and paste the rest of the commands from these instructions into a terminal window.
Line 29:		Line 19:
	Now you can ssh in as root. Do not forget to go back and comment this line out when you're done since it will be enabled on the resulting machine. You will be reminded again at the end of this doc.		Now you can ssh in as root. Do not forget to go back and comment this line out when you're done since it will be enabled on the resulting machine. You will be reminded again at the end of this doc.

	= Add required packages =		=== Add required packages ===

	{{cmd\|apk add {{pkg\|zfs}} {{pkg\|sfdisk}} {{pkg\|e2fsprogs}} {{pkg\|syslinux}}}}		{{cmd\|apk add {{pkg\|zfs}} {{pkg\|sfdisk}} {{pkg\|e2fsprogs}} {{pkg\|syslinux}}}}

	= Partition setup =		== Partition setup ==

	We're assuming that {{path\|/dev/sda}} is the target storage device here and in the rest of the document, but the name of the storage device you wish to install to may be different. To see a list of storage devices and determine the correct one, type {{codeline\|sfdisk -l}}.		We're assuming that {{path\|/dev/sda}} is the target storage device here and in the rest of the document, but the name of the storage device you wish to install to may be different. To see a list of storage devices and determine the correct one, type {{codeline\|sfdisk -l}}.
Line 39:		Line 29:
	{{cmd\|echo -e "/dev/sda1: start{{=}}1M,size{{=}}100M,bootable\n/dev/sda2: start{{=}}101M" \| sfdisk --quiet --label dos /dev/sda}}		{{cmd\|echo -e "/dev/sda1: start{{=}}1M,size{{=}}100M,bootable\n/dev/sda2: start{{=}}101M" \| sfdisk --quiet --label dos /dev/sda}}

	== Create device nodes ==		=== Create device nodes ===

	{{cmd\|mdev -s}}		{{cmd\|mdev -s}}

	== Create the {{path\|/boot}} filesystem ==		=== Create the {{path\|/boot}} filesystem ===

	{{cmd\|mkfs.ext4 /dev/sda1}}		{{cmd\|mkfs.ext4 /dev/sda1}}

	= ZFS setup =		== ZFS setup ==
	== Create the root zpool ==
			=== Create the root zpool ===

	{{cmd\|modprobe zfs		{{cmd\|modprobe zfs
Line 84:		Line 75:
	errors: No known data errors		errors: No known data errors

	== Create the required datasets and mount root ==		=== Create the required datasets and mount root ===

	{{cmd\|zfs create -o mountpoint{{=}}none -o canmount{{=}}off rpool/ROOT		{{cmd\|zfs create -o mountpoint{{=}}none -o canmount{{=}}off rpool/ROOT
Line 90:		Line 81:
	mount -t zfs rpool/ROOT/alpine /mnt/}}		mount -t zfs rpool/ROOT/alpine /mnt/}}

	== Mount the {{path\|/boot}} filesystem ==		=== Mount the {{path\|/boot}} filesystem ===

	{{cmd\|mkdir /mnt/boot/		{{cmd\|mkdir /mnt/boot/
	mount -t ext4 /dev/sda1 /mnt/boot/}}		mount -t ext4 /dev/sda1 /mnt/boot/}}

	== Enable ZFS' services ==		=== Enable ZFS' services ===

	{{cmd\|rc-update add zfs-import sysinit		{{cmd\|rc-update add zfs-import sysinit
	rc-update add zfs-mount sysinit}}		rc-update add zfs-mount sysinit}}

	= Install Alpine Linux =		== Install Alpine Linux ==

	{{cmd\|setup-disk /mnt		{{cmd\|setup-disk /mnt
	dd if{{=}}/usr/share/syslinux/mbr.bin of{{=}}/dev/sda # write mbr so we can boot}}		dd if{{=}}/usr/share/syslinux/mbr.bin of{{=}}/dev/sda # write mbr so we can boot}}

	= Reboot and enjoy! =		Reboot and enjoy!

	😉		'''NOTE:''' If you went with the optional step, be sure to disable root login after you reboot.

	~~'''NOTE~~:~~'''~~		== See also ==
	~~If you went with the optional step, be sure to disable root login after you reboot.~~		* [[ZFS]]
			* [https://openzfs.github.io/openzfs-docs/Getting%20Started/Alpine%20Linux/Root%20on%20ZFS.html OpenZFS Guide for Alpine Linux]
			[[Category:Filesystems]]

R5: fix link

2023-08-21T17:18:06Z

fix link

← Older revision		Revision as of 17:18, 21 August 2023
Line 3:		Line 3:
	= OpenZFS Guide =		= OpenZFS Guide =

	A guide on OpenZFS website supports native encryption, UEFI boot and legacy boot, and multi-disk. See [~~https://web.archive.org/web/20230326130051/~~https://openzfs.github.io/openzfs-docs/Getting%20Started/Alpine%20Linux/Root%20on%20ZFS~~/1-preparation~~.html here].		A guide on OpenZFS website supports native encryption, UEFI boot and legacy boot, and multi-disk. See [https://openzfs.github.io/openzfs-docs/Getting%20Started/Alpine%20Linux/Root%20on%20ZFS.html here].

	= Downloading Alpine =		= Downloading Alpine =

Zcrayfish: /* Create the root zpool */ Fix the box... Hope it works.

2023-08-15T16:18:30Z

Create the root zpool: Fix the box... Hope it works.

← Older revision		Revision as of 16:18, 15 August 2023
Line 77:		Line 77:
	scan: none requested		scan: none requested
	config:		config:

	NAME STATE READ WRITE CKSUM		NAME STATE READ WRITE CKSUM
	rpool ONLINE 0 0 0		rpool ONLINE 0 0 0
	sda2 ONLINE 0 0 0		sda2 ONLINE 0 0 0

	errors: No known data errors		errors: No known data errors

Zcrayfish: /* Create the root zpool */ Use cmd and codeline templates. Use unordered list.

2023-08-15T16:15:47Z

Create the root zpool: Use cmd and codeline templates. Use unordered list.

← Older revision		Revision as of 16:15, 15 August 2023
Line 50:		Line 50:
	== Create the root zpool ==		== Create the root zpool ==

	modprobe zfs		{{cmd\|modprobe zfs
	zpool create -f -o ashift=12 \		zpool create -f -o ashift{{=}}12 \
	-O acltype=posixacl -O canmount=off -O compression=lz4 \		-O acltype{{=}}posixacl -O canmount{{=}}off -O compression{{=}}lz4 \
	-O dnodesize=auto -O normalization=formD -O relatime=on -O xattr=sa \		-O dnodesize{{=}}auto -O normalization{{=}}formD -O relatime{{=}}on -O xattr{{=}}sa \
	-O encryption=aes-256-gcm -O keylocation=prompt -O keyformat=passphrase \		-O encryption{{=}}aes-256-gcm -O keylocation{{=}}prompt -O keyformat{{=}}passphrase \
	-O mountpoint=/ -R /mnt \		-O mountpoint{{=}}/ -R /mnt \
	rpool /dev/sda2		rpool /dev/sda2}}

	You will have to enter your passphrase at this point. Choose wisely, as your passphrase is most likely [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions#5-security-aspects the weakest link in this setup].		You will have to enter your passphrase at this point. Choose wisely, as your passphrase is most likely [https://gitlab.com/cryptsetup/cryptsetup/wikis/FrequentlyAskedQuestions#5-security-aspects the weakest link in this setup].

	A few notes on the options supplied to zpool:		A few notes on the options supplied to zpool:
			<ul>
	~~- `~~ashift=12` is recommended here because many drives today have 4KiB (or larger) physical sectors, even though they present 512B logical sectors		<li>{{codeline\|ashift{{=}}12}} is recommended here because many drives today have 4KiB (or larger) physical sectors, even though they present 512B logical sectors</li>
			<li>{{codeline\|acltype{{=}}posixacl}} enables POSIX ACLs globally</li>
	~~- `~~acltype=posixacl` enables POSIX ACLs globally		<li>{{codeline\|normalization{{=}}formD}} eliminates some corner cases relating to UTF-8 filename normalization. It also enables `utf8only=on`, meaning that only files with valid UTF-8 filenames will be accepted.</li>
			<li>{{codeline\|xattr{{=}}sa}} vastly improves the performance of extended attributes, but is Linux-only. If you care about using this pool on other OpenZFS implementation don't specify this option.</li></ul>
	~~- `~~normalization=formD` eliminates some corner cases relating to UTF-8 filename normalization. It also enables `utf8only=on`, meaning that only files with valid UTF-8 filenames will be accepted.

	~~- `~~xattr=sa` vastly improves the performance of extended attributes, but is Linux-only. If you care about using this pool on other OpenZFS implementation don't specify this option.

	After completing this, confirm that the pool has been created:		After completing this, confirm that the pool has been created:

	# zpool status		{{cmd\|# zpool status}}

	Should return something like:		Should return something like:

Zcrayfish: /* Create the required datasets and mount root */ use cmd template.

2023-08-15T16:10:21Z

Create the required datasets and mount root: use cmd template.

← Older revision		Revision as of 16:10, 15 August 2023
Line 89:		Line 89:
	== Create the required datasets and mount root ==		== Create the required datasets and mount root ==

	zfs create -o mountpoint=none -o canmount=off rpool/ROOT		{{cmd\|zfs create -o mountpoint{{=}}none -o canmount{{=}}off rpool/ROOT
	zfs create -o mountpoint=legacy rpool/ROOT/alpine		zfs create -o mountpoint{{=}}legacy rpool/ROOT/alpine
	mount -t zfs rpool/ROOT/alpine /mnt/		mount -t zfs rpool/ROOT/alpine /mnt/}}

	== Mount the {{path\|/boot}} filesystem ==		== Mount the {{path\|/boot}} filesystem ==

Zcrayfish: /* Mount the `/boot` filesystem */ use cmd template.

2023-08-15T16:09:15Z

Mount the `/boot` filesystem: use cmd template.

← Older revision		Revision as of 16:09, 15 August 2023
Line 93:		Line 93:
	mount -t zfs rpool/ROOT/alpine /mnt/		mount -t zfs rpool/ROOT/alpine /mnt/

	== Mount the `/boot` filesystem ==		== Mount the {{path\|/boot}} filesystem ==

	mkdir /mnt/boot/		{{cmd\|mkdir /mnt/boot/
	mount -t ext4 /dev/sda1 /mnt/boot/		mount -t ext4 /dev/sda1 /mnt/boot/}}

	== Enable ZFS' services ==		== Enable ZFS' services ==

Zcrayfish: /* Enable ZFS' services */ use cmd template.

2023-08-15T16:08:05Z

Enable ZFS' services: use cmd template.

← Older revision		Revision as of 16:08, 15 August 2023
Line 100:		Line 100:
	== Enable ZFS' services ==		== Enable ZFS' services ==

	rc-update add zfs-import sysinit		{{cmd\|rc-update add zfs-import sysinit
	rc-update add zfs-mount sysinit		rc-update add zfs-mount sysinit}}

	= Install Alpine Linux =		= Install Alpine Linux =

Zcrayfish: /* Install Alpine Linux */ use cmd template.

2023-08-15T16:06:57Z

Install Alpine Linux: use cmd template.

← Older revision		Revision as of 16:06, 15 August 2023
Line 105:		Line 105:
	= Install Alpine Linux =		= Install Alpine Linux =

	setup-disk /mnt		{{cmd\|setup-disk /mnt
	dd if=/usr/share/syslinux/mbr.bin of=/dev/sda # write mbr so we can boot		dd if{{=}}/usr/share/syslinux/mbr.bin of{{=}}/dev/sda # write mbr so we can boot}}


	= Reboot and enjoy! =		= Reboot and enjoy! =