quico-os-setup/arch-zbm
1
0
Fork 0
Code Issues 3 Pull Requests Packages Projects Releases Wiki Activity

docs(zfs): Explain ZFS dataset structure in plain English (#1)

Browse Source
This commit is contained in:
hygienic-books 2023-02-21 00:54:58 +01:00
parent 155e36dc60
commit 4bf236df75
1 changed files with 41 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
README.md
View File

@ -2,7 +2,7 @@
Helper script to install Arch Linux with ZFSBootMenu from within a running Arch Linux live CD ISO image
# Prep
## Prep
We expect minimal prep on your end. Please make sure that before execution the following conditions are met.
@ -14,7 +14,7 @@ The script will create a single ZFS zpool `zpool` on the `BF00` partition with d
The script will use the `EF00` partition to install a ZFSBootMenu EFI executable if `efibootmgr` says that no such `ZFSBootMenu` entry exists. If ZFSBootMenu gets added to the EFI partition it'll become primary boot option.
# How to run this?
## How to run this?
- Boot an Arch Linux live CD ISO image
- Run:
@ -24,7 +24,7 @@ The script will use the `EF00` partition to install a ZFSBootMenu EFI executable
```
During execution the script will call itself when it changes into its `chroot`, that's why we `export SCRIPT_URL`. Feel free to update `"${SCRIPT_URL}"` with whatever branch or revision you want to use from [quico.space/quico-os-setup/arch-zbm](https://quico.space/quico-os-setup/arch-zbm). Typically `.../branch/main/setup.sh` as shown above is what you want.
# Steps
## Steps
The scripts takes the following installation steps.
@ -35,7 +35,7 @@ The scripts takes the following installation steps.
1. Add ZFSBootMenu to `EF00` partition if it doesn't exist already
1. Exit into Arch Linux live CD ISO image shell for you to `reboot` and frolick
# Flavor choices
## Flavor choices
We make the following opinionated flavor choices. Feel free to change them to your liking.
@ -47,7 +47,7 @@ We make the following opinionated flavor choices. Feel free to change them to yo
- Timezone is `Etc/UTC`
- Check `timedatectl set-timezone <tzdata-zone>`
# Post-run manual steps
## Post-run manual steps
After installation you're going to want to at least touch these points in your new Arch Linux install:
@ -61,6 +61,42 @@ After installation you're going to want to at least touch these points in your n
- Local `root` account: The local `root` account's password is `password`.
- Arch User Repository (AUR) helper: We installed [paru](https://github.com/Morganamilo/paru) as our AUR helper, we installed from GitHub via `makepkg -si`.
# ZFS setup explained
The ZFS pool and dataset setup that makes this tick, explained in plain English.
1. Create zpool with options:
1. `-R /mnt` (aka `-o cachefile=none -o altroot=/mnt`). The pool is never cached, i.e. it's considered temporary. All pool and dataset mount paths have `/mnt` prepended. From `man zpoolprops`:
> This can be used when examining an unknown pool where the mount points cannot be trusted, or in an alternate boot environment, where the typical paths are not valid. `altroot` is not a persistent property. It is valid only while the system is up.
1. `-O canmount=off`: Note the capital `-O` which makes this a file system property, not a pool property. File system cannot be mounted, and is ignored by `zfs mount -a`. This property is not inherited.
1. `-O mountpoint=none`: What it says on the tin, the pool has no mountpoint configured.
1. `-O encryption=on`: Makes this our `encryptionroot` and passes the `encryption` setting to all child datasets. Selecting `encryption=on` when creating a dataset indicates that the default encryption suite will be selected, which is currently `aes-256-gcm`.
1. `-O keylocation=file://...`: This property is only set for encrypted datasets which are encryption roots. Controls where the user's encryption key will be loaded from by default for commands such as `zfs load-key`.
1. `-O keyformat=passphrase`: Controls what format the user's encryption key will be provided as. Passphrases must be between 8 and 512 bytes long.
1. At this time the newly created zpool is not mounted anywhere. Next we create the "root" dataset, that's an arbitary term for the parent dataset of all boot environments. Boot environments in your case may be for example different operating systems all of which live on separate datasets underneath the root.
1. `-o mountpoint=none`: Same as above, the root dataset has - just like the pool - no mountpoint configured.
1. `zfs set org.zfsbootmenu:commandline=...`: Set a common kernel command line for all boot environment such as `"ro quiet"`.
1. Neither the root dataset nor the pool are mounted at this time. We now create one boot environment dataset where we want to install Arch Linux.
1. `-o mountpoint=/`: Our Arch Linux dataset will be mounted at `/`.
zpool set bootfs="zroot/ROOT/$1" zroot
1. `-o canmount=noauto`: When set to `noauto`, a dataset can only be mounted and unmounted explicitly. The dataset is not mounted automatically when the dataset is created or imported, nor is it mounted by the `zfs mount -a` command or unmounted by the `zfs unmount -a` command.
1. We explicitly mount the boot environment. Since the entire pool is still subject to our initial `-R /mnt` during creation a `zfs mount zpool/root/archlinux` will mount the Arch Linux dataset not into `/` but instead into `/mnt`.
1. We also create a `data` dataset that - at least for now - we use to store only our `/home` data.
1. For `zpool/data`:
1. `-o mountpoint=/`: We use the `mountpoint` property here only for inheritance.
1. `-o canmount=off`: The `zpool/data` dataset itself cannot actually be mounted.
1. For a `zpool/data/home` child dataset:
1. We do not specify any properties. Since `canmount` cannot be inherited the parent's `canmount=off` does not apply, it instead defaults to `canmount=on`. The parent's `mountpoint=/` property on the other hand is inherited so for a `home` child dataset it conveniently equals `mountpoint=/home`.
1. In effect this `zpool/data/home` dataset is subject to `zfs mount -a` and will happily automount into `/home`.
1. We export the zpool once, we then reimport it by scanning only inside `/dev/disk/by-id`, again setting `-R /mnt` as we did during pool creation a moment ago and we do not mount any file systems.
1. We `zfs load-key <encryptionroot>` which will load the key from `keylocation` after which the `keystatus` property for `<encryptionroot>` and all child datasets will change from `unavailable` to `available`.
1. We mount our Arch Linux boot environment dataset. It automatically get prepended with `-R /mnt` since that's how we imported the pool.
1. We `zfs mount -a` which automounts `zpool/data/home` into `/home`, which again gets auto-prepended by `/mnt`.
1. We lastly mount our EFI partition into `/mnt/efi`.
1. We instruct ZFS to save its pool configuration via `zpool set cachefile=/etc/zfs/zpool.cache zpool`.
The complete ZFS structure now exists and is mounted at `/mnt` ready for any `pacstrap`, [debootstrap](https://wiki.debian.org/Debootstrap), `dnf --installroot` or other bootstrapping action.
# Development
## Conventional commits