Clarify and improve encryption documentation

- Remove the language that "all user data" is encrypted.  This is to
  avoid misunderstandings or arguments about what is "user data",
  especially in light of "user properties".
- Document that properties are unencrypted.
- Document that snapshot names are unencrypted.
- For consistency with the rest of the zfs.8 man page, use "ZFS" as the
  generic noun, not (bolded) "zfs".  The latter refers to the command.
  Likewise, use "ZFS" instead of "the kernel module".
- Give "a passphrase" as an example of a "user's key".

Reviewed-by: Tom Caputi <tcaputi@datto.com>
Reviewed-by: Brian Behlendorf <behlendorf1@llnl.gov>
Reviewed-by: George Melikov <mail@gmelikov.ru>
Signed-off-by: Richard Laager <rlaager@wiktel.com>
Closes #8652

diff --git a/man/man8/zfs.8 b/man/man8/zfs.8
index a8e859bdc53b7cd023a1ca18845a89db43c00c96..3b118ac3e9670c6b2328681eeacc2cd0e53b7ed0 100644 (file)
--- a/man/man8/zfs.8
+++ b/man/man8/zfs.8
@@ -2380,17 +2380,19 @@ configuration is not supported.
 .Ss Encryption
 Enabling the
 .Sy encryption
-feature allows for the creation of encrypted filesystems and volumes.
-.Nm
-will encrypt all user data including file and zvol data, file attributes,
-ACLs, permission bits, directory listings, FUID mappings, and userused /
-groupused data.
-.Nm
-will not encrypt metadata related to the pool structure, including dataset
-names, dataset hierarchy, file size, file holes, and dedup tables. Key rotation
-is managed internally by the  kernel module and changing the user's key does not
-require re-encrypting the entire dataset. Datasets can be scrubbed, resilvered,
-renamed, and deleted without the encryption keys being loaded (see the
+feature allows for the creation of encrypted filesystems and volumes.  ZFS
+will encrypt file and zvol data, file attributes, ACLs, permission bits,
+directory listings, FUID mappings, and
+.Sy userused
+/
+.Sy groupused
+data.  ZFS will not encrypt metadata related to the pool structure, including
+dataset and snapshot names, dataset hierarchy, properties, file size, file
+holes, and deduplication tables.
+.Pp
+Key rotation is managed by ZFS.  Changing the user's key (e.g. a passphrase)
+does not require re-encrypting the entire dataset.  Datasets can be scrubbed,
+resilvered, renamed, and deleted without the encryption keys being loaded (see the
 .Nm zfs Cm load-key
 subcommand for more info on key loading).
 .Pp
@@ -2432,8 +2434,7 @@ read-only
 .Sy encryptionroot
 property.
 .Pp
-Encryption changes the behavior of a few
-.Nm
+Encryption changes the behavior of a few ZFS
 operations. Encryption is applied after compression so compression ratios are
 preserved. Normally checksums in ZFS are 256 bits long, but for encrypted data
 the checksum is 128 bits of the user-chosen checksum and 128 bits of MAC from