docs(zfs): Export zpool when done working on it (#3)

README.md

@@ -32,9 +32,9 @@ The result will be something like this at which point you can start the `setup.s
 NAME         MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
 /dev/loop0     7:0    0 685.5M  1 loop /run/archiso/airootfs
 /dev/sr0      11:0    1 808.3M  0 rom  /run/archiso/bootmnt
-/dev/sda    202:0    0    20G  0 disk
+/dev/sda    202:0    0    10G  0 disk
 ├─/dev/sda1 202:1    0   512M  0 part
-└─/dev/sda2 202:2    0  19.5G  0 part
+└─/dev/sda2 202:2    0   9.5G  0 part
 ```
 
 ## ZFS dataset layout
@@ -404,6 +404,78 @@ Lastly create the dataset you want mounted:
 zfs create zpool/data/var/lib/docker
 ```
 
+## Mounting zpool for maintenance
+
+In case you want to mount your zpool on an external operating system such as an Arch Linux live CD ISO image do it like so:
+
+```
+zpool import zpool -d /dev/disk/by-partuuid -R /mnt -f -N
+zfs load-key -L prompt zpool
+zfs mount zpool/root/archlinux
+zfs mount -a
+mount /dev/sda1 /mnt/efi
+arch-chroot /mnt /bin/bash
+```
+
+When done exit `chroot` and cleanly remove your work:
+
+```
+umount /mnt/efi
+zfs umount -a
+zpool export zpool
+```
+
+Explanation:
+
+- We always want to mount pools `by-partuuid` for consistency so we specifically only look for pools at `/dev/disk/by-partuuid`.
+- We mount our zpool with `-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.
+- With `-f` and `-N` we force-mount our pool (`-f`) even if it previously wasn't cleanly exported; and we do not auto-mount any of its datasets (`-N`), not even the ones that have `canmount=on` set.
+
+    ```
+    # zfs list -oname,mountpoint,canmount,mounted
+    NAME                  MOUNTPOINT  CANMOUNT  MOUNTED
+    zpool                 none        off       no
+    zpool/data            /mnt        off       no
+    zpool/data/home       /mnt/home   on        no <-- Not immediately mounted
+    zpool/root            none        off       no
+    zpool/root/archlinux  /mnt        noauto    no <-- Not immediately mounted
+    ```
+- We load the decryption key by temporarily overriding the `keylocation` property to `-L prompt`. The default value is `file:///etc/zfs/zpool.key` which in all likelihood doesn't exist in this environment.
+- We mount our desired boot environment with `zfs mount zpool/root/archlinux`
+
+    ```
+    # zfs list -oname,mountpoint,canmount,mounted
+    NAME                  MOUNTPOINT  CANMOUNT  MOUNTED
+    zpool                 none        off       no
+    zpool/data            /mnt        off       no
+    zpool/data/home       /mnt/home   on        no
+    zpool/root            none        off       no
+    zpool/root/archlinux  /mnt        noauto    yes <-- Only boot env now mounted
+    ```
+- We mount all child datasets with `zfs mount -a` making `/mnt/home` available as well as any others you may have created yourself.
+
+    ```
+    # zfs list -oname,mountpoint,canmount,mounted
+    NAME                  MOUNTPOINT  CANMOUNT  MOUNTED
+    zpool                 none        off       no
+    zpool/data            /mnt        off       no
+    zpool/data/home       /mnt/home   on        yes <-- Now mounted
+    zpool/root            none        off       no
+    zpool/root/archlinux  /mnt        noauto    yes <-- Now mounted
+    ```
+- We lastly mount our EFI system partition (ESP), in this example it's living at `/dev/sda1` so adjust this path accordingly.
+
+    ```
+    # df -hTP
+    Filesystem           Type      Size  Used Avail Use% Mounted on
+    ...                  ...       ...    ...   ...  ... ...
+    zpool/root/archlinux zfs       8.6G  2.5G  6.2G  29% /mnt
+    zpool/data/home      zfs       6.3G  161M  6.2G   3% /mnt/home
+    /dev/sda1            vfat      511M   31M  481M   6% /mnt/efi
+    ```
+- We're ready to `arch-chroot` into our boot environment.
+
 # Development
 
 ## Conventional commits

setup.sh

@@ -564,7 +564,7 @@ Components:
   Enabled: false
 EFI:
   ImageDir: /efi/EFI/ZBM
-  Versions: 1
+  Versions: false
   Enabled: true
   Stub: /etc/zfsbootmenu/stub-loader.d/linuxx64.efi.stub
 Kernel:
@@ -705,8 +705,7 @@ function set_new_uefi_boot_entries () {
         efi_disks_list="$(get_disks_with_one_efipart)"
         if grep -Piq -- '^'"${efi_drive}"'$' <<<"${efi_disks_list}"; then
             for uefi_image in "${uefi_images[@]}"; do
-                uefi_image_version="$(basename "${uefi_image##*-}")"
+                uefi_image_version="$(basename "${uefi_image%%.EFI}")"
-                uefi_image_version="${uefi_image_version%%.EFI}"
                 uefi_image_inverted="${uefi_image#/mnt/efi}"
                 uefi_image_inverted="${uefi_image_inverted//\//\\}"
                 efibootmgr --disk "${efi_drive}" \

zbm_set_new_uefi_boot_entries.sh

@@ -94,8 +94,7 @@ function select_part () {
         esac
         >&3 printf -- '%s\n' \
             'It looks as if there is no '"${part_type_human_readable}" \
-            'on any of the disks. Did you correctly partition a disk before starting?' \
+            'on any of the disks. Is this a chroot? Exiting ...'
-            'Check https://quico.space/quico-os-setup/arch-zbm#prep. Exiting ...'
         exit 77
     fi
 
@@ -159,8 +158,7 @@ function set_new_uefi_boot_entries () {
         efi_disks_list="$(get_disks_with_one_efipart)"
         if grep -Piq -- '^'"${efi_drive}"'$' <<<"${efi_disks_list}"; then
             for uefi_image in "${uefi_images[@]}"; do
-                uefi_image_version="$(basename "${uefi_image##*-}")"
+                uefi_image_version="$(basename "${uefi_image%%.EFI}")"
-                uefi_image_version="${uefi_image_version%%.EFI}"
                 uefi_image_inverted="${uefi_image#/efi}"
                 uefi_image_inverted="${uefi_image_inverted//\//\\}"
                 efibootmgr --disk "${efi_drive}" \