README.md

@@ -404,6 +404,70 @@ 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'
+```
+
+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