Encryption: document snapshot corruption

There is a known issue reported on Linux and FreeBSD whereby snapshots experience runtime corruption when using ZFS native encryption. This filesystem is far too reliable for that to be a surprise until it can be fixed. OpenZFS bug: #12014 FreeBSD bug: #282622 Signed-off-by: Alexander Ziaee <[email protected]> Co-authored-by: Lexi Winter <[email protected]>
openzfs · Nov 12, 2024 · 0a8f852 · 0a8f852
1 parent 1c9a4c8
commit 0a8f852
Show file tree

Hide file tree

Showing 2 changed files with 14 additions and 10 deletions.
diff --git a/man/man7/zfsprops.7 b/man/man7/zfsprops.7
@@ -162,18 +162,15 @@ For encrypted datasets, indicates where the dataset is currently inheriting its
 encryption key from.
 Loading or unloading a key for the
 .Sy encryptionroot
-will implicitly load / unload the key for any inheriting datasets (see
-.Nm zfs Cm load-key
-and
-.Nm zfs Cm unload-key
-for details).
+will implicitly load / unload the key for any inheriting datasets
 Clones will always share an
 encryption key with their origin.
 See the
 .Sx Encryption
 section of
 .Xr zfs-load-key 8
-for details.
+for details and known
+.Sx BUGS .
 .It Sy filesystem_count
 The total number of filesystems and volumes that exist under this location in
 the dataset tree.
@@ -188,9 +185,9 @@ The possible values are
 and
 .Sy unavailable .
 See
-.Nm zfs Cm load-key
+.Xr zfs-load-key 8
 and
-.Nm zfs Cm unload-key .
+.Xr zfs-unload-key 8 .
 .It Sy guid
 The 64 bit GUID of this dataset or bookmark which does not change over its
 entire lifetime.
@@ -1148,7 +1145,9 @@ selected, which is currently
 In order to provide consistent data protection, encryption must be specified at
 dataset creation time and it cannot be changed afterwards.
 .Pp
-For more details and caveats about encryption see the
+For more details about encryption and known
+.Sx BUGS ,
+see the
 .Sx Encryption
 section of
 .Xr zfs-load-key 8 .

diff --git a/man/man8/zfs-load-key.8 b/man/man8/zfs-load-key.8
@@ -222,7 +222,9 @@ that has an encrypted parent.
 .Ss Encryption
 Enabling the
 .Sy encryption
-feature allows for the creation of encrypted filesystems and volumes.
+feature allows for the creation of encrypted filesystems and volumes,
+but not yet snapshots
+.Pq see Sx BUGS .
 ZFS will encrypt file and volume data, file attributes, ACLs, permission bits,
 directory listings, FUID mappings, and
 .Sy userused Ns / Ns Sy groupused
@@ -302,3 +304,6 @@ written.
 .Xr zfsprops 7 ,
 .Xr zfs-create 8 ,
 .Xr zfs-set 8
+.Sh BUGS
+ZFS native encryption has known issues
+causing runtime data corruption in snapshots.