Handbook - ZFS: how to mount encrypted zpool with geli

PR: 240421

1 files changed, 18 insertions, 0 deletions

diff --git a/documentation/content/en/books/handbook/zfs/_index.adoc b/documentation/content/en/books/handbook/zfs/_index.adoc
index 86058d1446..86f3ef473a 100644
--- a/documentation/content/en/books/handbook/zfs/_index.adoc
+++ b/documentation/content/en/books/handbook/zfs/_index.adoc
@@ -1736,6 +1736,24 @@ At boot, the ZFS startup scripts enabled by `zfs_enable="YES"` in [.filename]#/e
 Importing a pool adds it to that cache file automatically; the `cachefile` pool property controls this behavior.
 Pools imported with `cachefile=none` do not come back automatically after a reboot.
 
+[[zfs-zpool-import-geli]]
+==== Importing a GELI-Encrypted Pool
+
+The `Encrypt Disks` option of the FreeBSD installer encrypts the pool's partitions with man:geli[8], described in crossref:disks[disks-encrypting-geli,"Encrypting Disk Partitions"], rather than with crossref:zfs[zfs-native-encryption,ZFS native encryption].
+On the installed system the loader prompts for the passphrase and attaches the providers before mounting the root pool, but ZFS itself knows nothing about the encryption: when booting from rescue media or moving the disks to another host, `zpool import` does not find the pool until the GELI providers are attached.
+
+Attach the encrypted [.filename]#freebsd-zfs# partition of every disk in the pool, supplying the passphrase, then import the pool:
+
+[source,shell]
+....
+# geli attach ada0p4
+Enter passphrase:
+# zpool import -f -R /mnt zroot
+....
+
+Use `gpart show` to identify the [.filename]#freebsd-zfs# partitions; with the default installer layout the encrypted partition is [.filename]#p4#.
+Systems installed with the legacy layout, which keeps a separate unencrypted boot pool, additionally store a key file in [.filename]#/boot/encryption.key# on that pool; attach those providers with `geli attach -k /path/to/encryption.key`.
+
 [[zfs-zpool-upgrade]]
 === Upgrading a Storage Pool