man: document --repair-crypt-mismatches and --free-crypt-fallback

zpool-scrub(8) gets two new option entries describing the new flags
introduced by the BP_USES_CRYPT repair pipeline. zpoolconcepts(7)
gets a new "Encryption Flag Mismatches Repair" subsection summarising
the bug class, the three repair dispositions (Mode 1.5 smart flip,
Mode 3 hole+free, log-only for unrepairable indirects), the
eligibility skip list, and the existing user-space alternative
('zfs send -U | zfs recv' onto a fresh pool).

Both pages validate cleanly via 'man --warnings -Z'.

No code changes.

Refs: openzfs#14330 openzfs#15275 openzfs#15464 openzfs#16065 openzfs#18587
Signed-off-by: Jerzy Kołosowski <jerzy@kolosowscy.pl>

Author: jkolo

man/man7/zpoolconcepts.7

@@ -349,6 +349,83 @@ ZFS attempts to bring the device online automatically.
 Device attachment detection is hardware-dependent
 and might not be supported on all platforms.
 .
+.Ss Encryption Flag Mismatches Repair
+On natively encrypted datasets every block pointer must carry the
+.Sy BP_USES_CRYPT
+flag.
+A small class of rare write-path corruption can leave that flag clear
+on otherwise-encrypted blocks; the symptom is an
+.Sy EIO
+on read of the affected offset and, historically, a kernel panic in
+.Fn zfs_mknode .
+Issues
+.Pq see Sy openzfs/zfs#14330 #15275 #15464 #16065
+have been reported intermittently from ZFS 2.0.x through 2.4.x.
+.Pp
+.Nm zpool Cm scrub
+detects this state and reports the affected file in
+.Nm zpool Cm status Fl v .
+With the
+.Sy crypt_repair
+feature enabled
+.Pq read-compatible ,
+the
+.Fl -repair-crypt-mismatches
+scrub flag attempts in-kernel recovery per BP, in this order:
+.Bl -bullet -compact -offset indent
+.It
+.Em Smart flip
+.Pq Mode 1.5 :
+decrypt the on-disk block under the dataset key, recompute the MAC, and
+if it matches the value stored in
+.Sy blk_cksum ,
+restore the CRYPT flag on the parent dnode or indirect block.
+Lossless - no data is rewritten.
+.It
+.Em Hole and free
+.Pq Mode 3 .
+If MAC verification fails on a leaf block and the operator opted in
+with
+.Fl -free-crypt-fallback ,
+the leaf is freed and the parent's reference becomes a hole.
+The affected file accumulates zeros at that offset; the rest of the
+file remains accessible.
+Destructive - not enabled unless explicitly requested.
+.It
+.Em Log only .
+For an indirect BP whose MAC-of-MAC verification fails, the block is
+left in
+.Nm zpool Cm status Fl v
+for operator follow-up.
+Automatic free of an indirect would orphan its entire subtree, so it
+is not attempted.
+.El
+.Pp
+Several BP classes are skipped without attempting repair, with the
+reason logged via
+.Nm zpool Cm events :
+snapshots, MOS objects, special dnodes
+.Pq Sy DMU_OBJECT_IS_SPECIAL
+where
+.Sy dn_dbuf
+can be NULL,
+.Sy ZIL
+blocks,
+.Sy DMU_OT_OBJSET
+blocks
+.Pq separate authenticated-MAC API ,
+gang blocks, deduplicated BPs, and datasets whose key is not loaded.
+.Pp
+An alternative recovery path that does not require kernel changes is
+.Nm zfs Cm send Fl U
+plus
+.Nm zfs Cm receive
+onto a freshly created pool; the encryption pipeline runs again on
+ingest and produces correct BPs.
+This works without the
+.Sy crypt_repair
+feature but is heavier-weight than the in-kernel paths above.
+.
 .Ss Hot Spares
 ZFS allows devices to be associated with pools as
 .Qq hot spares .

man/man8/zpool-scrub.8

@@ -42,6 +42,8 @@
 .Op Fl w
 .Op Fl S Ar date
 .Op Fl E Ar date
+.Op Fl -repair-crypt-mismatches
+.Op Fl -free-crypt-fallback
 .Fl a Ns | Ns Ar pool Ns …
 .
 .Sh DESCRIPTION
@@ -166,7 +168,80 @@ Specifying dates prior to enabling this feature will result in scrubbing
 starting from the date the pool was created.
 If the time was moved backward manually the data range may become inaccurate.
 .El
-.Sh EXAMPLES
+.It Fl -repair-crypt-mismatches
+Attempt in-kernel repair of any block pointer found on an encrypted
+dataset that lacks the
+.Sy BP_USES_CRYPT
+flag.
+This corruption class has been reported intermittently on natively
+encrypted datasets across ZFS 2.0.x through 2.4.x; without this flag
+the read path returns
+.Sy EIO
+and the create path historically panicked in
+.Fn zfs_mknode .
+.Pp
+When set, the scrub examines each detected mismatch and dispatches one
+of two repair paths:
+.Bl -bullet -compact -offset indent
+.It
+.Em Smart flip
+.Pq Mode 1.5 .
+If decryption of the on-disk block succeeds and the MAC stored in
+.Sy blk_cksum
+verifies under the dataset key, the block is genuinely encrypted
+ciphertext that lost only its CRYPT flag in flight.
+The flag is restored atomically on the parent dnode or indirect block;
+no data is rewritten.
+This repair is lossless.
+.It
+.Em No repair .
+If MAC verification fails, the on-disk bytes are not legitimate
+ciphertext under the dataset key.
+The block is logged in
+.Nm zpool Cm status Fl v
+for the operator to handle; no further action is taken unless
+.Fl -free-crypt-fallback
+is also set
+.Pq see below .
+.El
+.Pp
+Several BP classes are intentionally skipped and recorded as such in
+.Nm zpool Cm events :
+snapshot datasets (the parent BP is immutable), MOS objects, special
+dnodes
+.Pq dn_dbuf can be NULL ,
+ZIL blocks, objset blocks
+.Pq use a different authenticated MAC API ,
+gang blocks, deduplicated BPs
+.Pq the DDT key includes the CRYPT bit ,
+and datasets whose encryption key is not loaded.
+.Pp
+The repair pipeline requires the
+.Sy feature@crypt_repair
+pool feature to be enabled.
+Indirect blocks are MAC-of-MAC verified the same way as leaves; only
+the destructive
+.Fl -free-crypt-fallback
+path is restricted to leaves.
+.It Fl -free-crypt-fallback
+When a leaf block fails Mode 1.5 MAC verification under
+.Fl -repair-crypt-mismatches ,
+free the leaf and replace the parent's reference with a hole.
+The affected file accumulates zeros at the offset of the freed block;
+the rest of the file remains accessible.
+.Pp
+This flag is destructive
+.Pq the original bytes are released ,
+opt-in only, and applies to leaf BPs only.
+Indirect blocks are never auto-freed because doing so would orphan their
+entire subtree; an unrepairable indirect is left in
+.Nm zpool Cm status Fl v
+for the operator to handle out of band.
+.Pp
+.Fl -free-crypt-fallback
+requires
+.Fl -repair-crypt-mismatches
+to also be set.
 .Ss Example 1
 Status of pool with ongoing scrub:
 .sp