implement thorough scrub support (zpool scrub -t)

This introduces the -t (thorough) flag to 'zpool scrub' command.
A thorough scrub decrypts and decompresses blocks as they are read,
allowing ZFS to catch rare corruption scenarios where the block's
checksum matches the data on disk, but the block fails to decrypt
or decompress.

For encrypted datasets, the keys must be loaded to perform a thorough
scrub. If the keys are not loaded, or are unloaded while the scrub is
in progress, the scrub will fall back to a normal scrub
for those encrypted blocks with key unloaded.

Signed-off-by: Alek Pinchuk <apinchuk@axcient.com>

Author: alek-p

cmd/zpool/zpool_main.c

@@ -59,6 +59,7 @@
 #include <sys/wait.h>
 #include <zfs_prop.h>
 #include <sys/fs/zfs.h>
+#include <sys/dsl_scan.h>
 #include <sys/stat.h>
 #include <sys/systeminfo.h>
 #include <sys/fm/fs/zfs.h>
@@ -512,8 +513,9 @@ get_usage(zpool_help_t idx)
 		return (gettext("\tinitialize [-c | -s | -u] [-w] <-a | <pool> "
 		    "[<device> ...]>\n"));
 	case HELP_SCRUB:
-		return (gettext("\tscrub [-e | -s | -p | -C | -E | -S] [-w] "
-		    "<-a | <pool> [<pool> ...]>\n"));
+		return (gettext("\tscrub [-e | -s | -p | -t | -C [-t] | "
+		    "(-E | -S) [-t]] [-w]\n"
+		    "\t    <-a | <pool> [<pool> ...]>\n"));
 	case HELP_RESILVER:
 		return (gettext("\tresilver <pool> ...\n"));
 	case HELP_TRIM:
@@ -8518,7 +8520,7 @@ date_string_to_sec(const char *timestr, boolean_t rounding)
 }
 
 /*
- * zpool scrub [-e | -s | -p | -C | -E | -S] [-w] [-a | <pool> ...]
+ * zpool scrub [-e | -s | -p | -C | -E | -S | -t] [-w] [-a | <pool> ...]
  *
  *	-a	Scrub all pools.
  *	-e	Only scrub blocks in the error log.
@@ -8527,6 +8529,7 @@ date_string_to_sec(const char *timestr, boolean_t rounding)
  *	-s	Stop.  Stops any in-progress scrub.
  *	-p	Pause. Pause in-progress scrub.
  *	-w	Wait.  Blocks until scrub has completed.
+ *	-t	Decompress and decrypt (if key is loaded) scrubbed blocks.
  *	-C	Scrub from last saved txg.
  */
 int
@@ -8538,24 +8541,26 @@ zpool_do_scrub(int argc, char **argv)
 	int error;
 
 	cb.cb_type = POOL_SCAN_SCRUB;
-	cb.cb_scrub_cmd = POOL_SCRUB_NORMAL;
+	cb.cb_scrub_cmd = 0;
 	cb.cb_date_start = cb.cb_date_end = 0;
 
 	boolean_t is_error_scrub = B_FALSE;
 	boolean_t is_pause = B_FALSE;
 	boolean_t is_stop = B_FALSE;
-	boolean_t is_txg_continue = B_FALSE;
 	boolean_t scrub_all = B_FALSE;
 
 	/* check options */
-	while ((c = getopt(argc, argv, "aspweCE:S:")) != -1) {
+	while ((c = getopt(argc, argv, "aspweCE:S:t")) != -1) {
 		switch (c) {
 		case 'a':
 			scrub_all = B_TRUE;
 			break;
 		case 'e':
 			is_error_scrub = B_TRUE;
 			break;
+		case 't':
+			cb.cb_scrub_cmd |= POOL_SCRUB_THOROUGH;
+			break;
 		case 'E':
 			/*
 			 * Round the date. It's better to scrub more data than
@@ -8576,7 +8581,7 @@ zpool_do_scrub(int argc, char **argv)
 			wait = B_TRUE;
 			break;
 		case 'C':
-			is_txg_continue = B_TRUE;
+			cb.cb_scrub_cmd |= POOL_SCRUB_FROM_LAST_TXG;
 			break;
 		case '?':
 			(void) fprintf(stderr, gettext("invalid option '%c'\n"),
@@ -8589,17 +8594,38 @@ zpool_do_scrub(int argc, char **argv)
 		(void) fprintf(stderr, gettext("invalid option "
 		    "combination: -s and -p are mutually exclusive\n"));
 		usage(B_FALSE);
-	} else if (is_pause && is_txg_continue) {
+	} else if (is_error_scrub && is_pause) {
+		(void) fprintf(stderr, gettext("invalid option "
+		    "combination: -e and -p are mutually exclusive\n"));
+		usage(B_FALSE);
+	} else if (is_error_scrub && is_stop) {
+		(void) fprintf(stderr, gettext("invalid option "
+		    "combination: -e and -s are mutually exclusive\n"));
+		usage(B_FALSE);
+	} else if (is_error_scrub &&
+	    (cb.cb_scrub_cmd & POOL_SCRUB_FROM_LAST_TXG)) {
+		(void) fprintf(stderr, gettext("invalid option "
+		    "combination: -e and -C are mutually exclusive\n"));
+		usage(B_FALSE);
+	} else if (is_error_scrub && (cb.cb_scrub_cmd & POOL_SCRUB_THOROUGH)) {
+		(void) fprintf(stderr, gettext("invalid option "
+		    "combination: -e and -t are mutually exclusive\n"));
+		usage(B_FALSE);
+	} else if (is_pause && (cb.cb_scrub_cmd & POOL_SCRUB_FROM_LAST_TXG)) {
 		(void) fprintf(stderr, gettext("invalid option "
 		    "combination: -p and -C are mutually exclusive\n"));
 		usage(B_FALSE);
-	} else if (is_stop && is_txg_continue) {
+	} else if (is_pause && (cb.cb_scrub_cmd & POOL_SCRUB_THOROUGH)) {
+		(void) fprintf(stderr, gettext("invalid option "
+		    "combination: -p and -t are mutually exclusive\n"));
+		usage(B_FALSE);
+	} else if (is_stop && (cb.cb_scrub_cmd & POOL_SCRUB_FROM_LAST_TXG)) {
 		(void) fprintf(stderr, gettext("invalid option "
 		    "combination: -s and -C are mutually exclusive\n"));
 		usage(B_FALSE);
-	} else if (is_error_scrub && is_txg_continue) {
+	} else if (is_stop && (cb.cb_scrub_cmd & POOL_SCRUB_THOROUGH)) {
 		(void) fprintf(stderr, gettext("invalid option "
-		    "combination: -e and -C are mutually exclusive\n"));
+		    "combination: -s and -t are mutually exclusive\n"));
 		usage(B_FALSE);
 	} else {
 		if (is_error_scrub)
@@ -8609,19 +8635,28 @@ zpool_do_scrub(int argc, char **argv)
 			cb.cb_scrub_cmd = POOL_SCRUB_PAUSE;
 		} else if (is_stop) {
 			cb.cb_type = POOL_SCAN_NONE;
-		} else if (is_txg_continue) {
-			cb.cb_scrub_cmd = POOL_SCRUB_FROM_LAST_TXG;
-		} else {
-			cb.cb_scrub_cmd = POOL_SCRUB_NORMAL;
 		}
 	}
 
+	uint64_t scrub_kind = cb.cb_scrub_cmd & POOL_SCRUB_THOROUGH;
+	if (scrub_kind == 0)
+		scrub_kind = POOL_SCRUB_NORMAL;
 	if ((cb.cb_date_start != 0 || cb.cb_date_end != 0) &&
-	    cb.cb_scrub_cmd != POOL_SCRUB_NORMAL) {
-		(void) fprintf(stderr, gettext("invalid option combination: "
-		    "start/end date is available only with normal scrub\n"));
+	    (cb.cb_scrub_cmd & POOL_SCRUB_FROM_LAST_TXG)) {
+		(void) fprintf(stderr, gettext("invalid option "
+		    "combination: -C and -S/-E date are mutually "
+		    "exclusive\n"));
+		usage(B_FALSE);
+	} else if ((cb.cb_date_start != 0 || cb.cb_date_end != 0) &&
+	    (is_error_scrub ||
+	    (scrub_kind != POOL_SCRUB_NORMAL &&
+	    scrub_kind != POOL_SCRUB_THOROUGH))) {
+		(void) fprintf(stderr, gettext("invalid option "
+		    "combination: start/end date is available only "
+		    "with normal or thorough scrub\n"));
 		usage(B_FALSE);
 	}
+
 	if (cb.cb_date_start != 0 && cb.cb_date_end != 0 &&
 	    cb.cb_date_start > cb.cb_date_end) {
 		(void) fprintf(stderr, gettext("invalid arguments: "
@@ -8941,7 +8976,7 @@ print_err_scrub_status(pool_scan_stat_t *ps)
  * Print out detailed scrub status.
  */
 static void
-print_scan_scrub_resilver_status(pool_scan_stat_t *ps)
+print_scan_scrub_resilver_status(pool_scan_stat_t *ps, boolean_t is_thorough)
 {
 	time_t start, end, pause;
 	uint64_t pass_scanned, scanned, pass_issued, issued, total_s, total_i;
@@ -8976,10 +9011,11 @@ print_scan_scrub_resilver_status(pool_scan_stat_t *ps)
 		secs_to_dhms(end - start, time_buf);
 
 		if (is_scrub) {
-			(void) printf(gettext("scrub repaired %s "
-			    "in %s with %llu errors on %s"), processed_buf,
-			    time_buf, (u_longlong_t)ps->pss_errors,
-			    ctime(&end));
+			(void) printf(gettext("%sscrub repaired %s "
+			    "in %s with %llu errors on %s"),
+			    is_thorough ? "thorough " : "",
+			    processed_buf, time_buf,
+			    (u_longlong_t)ps->pss_errors, ctime(&end));
 		} else if (is_resilver) {
 			(void) printf(gettext("resilvered %s "
 			    "in %s with %llu errors on %s"), processed_buf,
@@ -8989,7 +9025,8 @@ print_scan_scrub_resilver_status(pool_scan_stat_t *ps)
 		return;
 	} else if (ps->pss_state == DSS_CANCELED) {
 		if (is_scrub) {
-			(void) printf(gettext("scrub canceled on %s"),
+			(void) printf(gettext("%sscrub canceled on %s"),
+			    is_thorough ? "thorough " : "",
 			    ctime(&end));
 		} else if (is_resilver) {
 			(void) printf(gettext("resilver canceled on %s"),
@@ -9003,12 +9040,15 @@ print_scan_scrub_resilver_status(pool_scan_stat_t *ps)
 	/* Scan is in progress. Resilvers can't be paused. */
 	if (is_scrub) {
 		if (pause == 0) {
-			(void) printf(gettext("scrub in progress since %s"),
+			(void) printf(gettext("%sscrub in progress since %s"),
+			    is_thorough ? "thorough " : "",
 			    ctime(&start));
 		} else {
-			(void) printf(gettext("scrub paused since %s"),
+			(void) printf(gettext("%sscrub paused since %s"),
+			    is_thorough ? "thorough " : "",
 			    ctime(&pause));
-			(void) printf(gettext("\tscrub started on %s"),
+			(void) printf(gettext("\t%sscrub started on %s"),
+			    is_thorough ? "thorough " : "",
 			    ctime(&start));
 		}
 	} else if (is_resilver) {
@@ -10099,6 +10139,7 @@ print_scan_status(zpool_handle_t *zhp, nvlist_t *nvroot)
 	pool_checkpoint_stat_t *pcs = NULL;
 	pool_scan_stat_t *ps = NULL;
 	uint_t c;
+	boolean_t is_thorough = B_FALSE;
 	time_t scrub_start = 0, errorscrub_start = 0;
 
 	if (nvlist_lookup_uint64_array(nvroot, ZPOOL_CONFIG_SCAN_STATS,
@@ -10111,8 +10152,10 @@ print_scan_status(zpool_handle_t *zhp, nvlist_t *nvroot)
 		have_resilver = (ps->pss_func == POOL_SCAN_RESILVER);
 		have_scrub = (ps->pss_func == POOL_SCAN_SCRUB);
 		scrub_start = ps->pss_start_time;
-		if (c > offsetof(pool_scan_stat_t,
-		    pss_pass_error_scrub_pause) / 8) {
+		if (POOL_SCAN_STAT_VALID(pss_pass_scrub_flags, c) &&
+		    (ps->pss_pass_scrub_flags & DSF_SCRUB_THOROUGH) != 0)
+			is_thorough = B_TRUE;
+		if (POOL_SCAN_STAT_VALID(pss_pass_error_scrub_pause, c)) {
 			have_errorscrub = (ps->pss_error_scrub_func ==
 			    POOL_SCAN_ERRORSCRUB);
 			errorscrub_start = ps->pss_error_scrub_start;
@@ -10124,7 +10167,7 @@ print_scan_status(zpool_handle_t *zhp, nvlist_t *nvroot)
 
 	/* Always print the scrub status when available. */
 	if (have_scrub && scrub_start > errorscrub_start)
-		print_scan_scrub_resilver_status(ps);
+		print_scan_scrub_resilver_status(ps, is_thorough);
 	else if (have_errorscrub && errorscrub_start >= scrub_start)
 		print_err_scrub_status(ps);
 
@@ -10134,7 +10177,7 @@ print_scan_status(zpool_handle_t *zhp, nvlist_t *nvroot)
 	 */
 	if (active_resilver || (!active_rebuild && have_resilver &&
 	    resilver_end_time && resilver_end_time > rebuild_end_time)) {
-		print_scan_scrub_resilver_status(ps);
+		print_scan_scrub_resilver_status(ps, is_thorough);
 	} else if (active_rebuild || (!active_resilver && have_rebuild &&
 	    rebuild_end_time && rebuild_end_time > resilver_end_time)) {
 		print_rebuild_status(zhp, nvroot);

cmd/ztest.c

@@ -4230,7 +4230,7 @@ ztest_device_removal(ztest_ds_t *zd, uint64_t id)
 	 * strategy employed by ztest_fault_inject() when selecting which
 	 * offset are redundant and can be damaged.
 	 */
-	error = spa_scan(spa, POOL_SCAN_SCRUB);
+	error = spa_scan(spa, POOL_SCAN_SCRUB, POOL_SCRUB_NORMAL);
 	if (error == 0) {
 		while (dsl_scan_scrubbing(spa_get_dsl(spa)))
 			txg_wait_synced(spa_get_dsl(spa), 0);
@@ -6704,7 +6704,7 @@ ztest_fault_inject(ztest_ds_t *zd, uint64_t id)
 	mutex_exit(&ztest_vdev_lock);
 
 	if (injected && ztest_opts.zo_raid_do_expand) {
-		int error = spa_scan(spa, POOL_SCAN_SCRUB);
+		int error = spa_scan(spa, POOL_SCAN_SCRUB, POOL_SCRUB_NORMAL);
 		if (error == 0) {
 			while (dsl_scan_scrubbing(spa_get_dsl(spa)))
 				txg_wait_synced(spa_get_dsl(spa), 0);
@@ -6737,7 +6737,7 @@ ztest_fault_inject(ztest_ds_t *zd, uint64_t id)
 static int
 ztest_scrub_impl(spa_t *spa)
 {
-	int error = spa_scan(spa, POOL_SCAN_SCRUB);
+	int error = spa_scan(spa, POOL_SCAN_SCRUB, POOL_SCRUB_NORMAL);
 	if (error)
 		return (error);
 
@@ -6771,7 +6771,7 @@ ztest_scrub(ztest_ds_t *zd, uint64_t id)
 	/*
 	 * Start a scrub, wait a moment, then force a restart.
 	 */
-	(void) spa_scan(spa, POOL_SCAN_SCRUB);
+	(void) spa_scan(spa, POOL_SCAN_SCRUB, POOL_SCRUB_NORMAL);
 	(void) poll(NULL, 0, 100);
 
 	error = ztest_scrub_impl(spa);
@@ -7464,7 +7464,7 @@ ztest_spa_import_export(char *oldname, char *newname)
 	 * Kick off a scrub to tickle scrub/export races.
 	 */
 	if (ztest_random(2) == 0)
-		(void) spa_scan(spa, POOL_SCAN_SCRUB);
+		(void) spa_scan(spa, POOL_SCAN_SCRUB, POOL_SCRUB_NORMAL);
 
 	pool_guid = spa_guid(spa);
 	spa_close(spa, FTAG);

include/sys/dsl_scan.h

@@ -76,6 +76,7 @@ typedef struct dsl_scan_phys {
 typedef enum dsl_scan_flags {
 	DSF_VISIT_DS_AGAIN = 1<<0,
 	DSF_SCRUB_PAUSED = 1<<1,
+	DSF_SCRUB_THOROUGH = 1<<2,
 } dsl_scan_flags_t;
 
 #define	DSL_SCAN_FLAGS_MASK (DSF_VISIT_DS_AGAIN)
@@ -184,6 +185,7 @@ typedef struct {
 	pool_scan_func_t func;
 	uint64_t	 txgstart;
 	uint64_t	 txgend;
+	dsl_scan_flags_t flags;
 } setup_sync_arg_t;
 
 typedef struct dsl_scan_io_queue dsl_scan_io_queue_t;
@@ -197,7 +199,7 @@ void dsl_scan_fini(struct dsl_pool *dp);
 void dsl_scan_sync(struct dsl_pool *, dmu_tx_t *);
 int dsl_scan_cancel(struct dsl_pool *);
 int dsl_scan(struct dsl_pool *, pool_scan_func_t, uint64_t starttxg,
-    uint64_t txgend);
+    uint64_t txgend, dsl_scan_flags_t flags);
 void dsl_scan_assess_vdev(struct dsl_pool *dp, vdev_t *vd);
 boolean_t dsl_scan_scrubbing(const struct dsl_pool *dp);
 boolean_t dsl_errorscrubbing(const struct dsl_pool *dp);

include/sys/fs/zfs.h

@@ -1203,13 +1203,22 @@ typedef enum pool_scan_func {
 } pool_scan_func_t;
 
 /*
- * Used to control scrub pause and resume.
+ * POOL_SCRUB_NORMAL, POOL_SCRUB_PAUSE, and POOL_SCRUB_FROM_LAST_TXG have
+ * their historical integer values (0, 1, 2) for user/kernel ABI
+ * compatibility.
+ *
+ * POOL_SCRUB_THOROUGH uses a non-colliding value so it can be combined with
+ * POOL_SCRUB_FROM_LAST_TXG. "Normal" scrub is implied when the thorough
+ * bit is clear (command 0, 2, or date-scrub with command 0).
+ *
+ * POOL_SCRUB_PAUSE must appear alone (scan_command == 1).
  */
 typedef enum pool_scrub_cmd {
 	POOL_SCRUB_NORMAL = 0,
-	POOL_SCRUB_PAUSE,
-	POOL_SCRUB_FROM_LAST_TXG,
-	POOL_SCRUB_FLAGS_END
+	POOL_SCRUB_PAUSE = 1,
+	POOL_SCRUB_FROM_LAST_TXG = 2,
+	POOL_SCRUB_FLAGS_END = 3,
+	POOL_SCRUB_THOROUGH = 8,
 } pool_scrub_cmd_t;
 
 typedef enum {
@@ -1302,9 +1311,15 @@ typedef struct pool_scan_stat {
 	/* error scrub values not stored on disk */
 	/* error scrub pause time in milliseconds */
 	uint64_t	pss_pass_error_scrub_pause;
+	uint64_t	pss_pass_scrub_flags;
 
 } pool_scan_stat_t;
 
+#define	POOL_SCAN_STAT_VALID(field, uint64_t_field_count) \
+	((uint64_t_field_count * sizeof (uint64_t)) >= \
+	(offsetof(pool_scan_stat_t, field) + \
+	sizeof (((pool_scan_stat_t *)NULL)->field)))
+
 typedef struct pool_removal_stat {
 	uint64_t prs_state; /* dsl_scan_state_t */
 	uint64_t prs_removing_vdev;

include/sys/spa.h

@@ -848,9 +848,9 @@ extern void spa_l2cache_activate(vdev_t *vd);
 extern void spa_l2cache_drop(spa_t *spa);
 
 /* scanning */
-extern int spa_scan(spa_t *spa, pool_scan_func_t func);
+extern int spa_scan(spa_t *spa, pool_scan_func_t func, uint64_t flags);
 extern int spa_scan_range(spa_t *spa, pool_scan_func_t func, uint64_t txgstart,
-    uint64_t txgend);
+    uint64_t txgend, uint64_t flags);
 extern int spa_scan_stop(spa_t *spa);
 extern int spa_scrub_pause_resume(spa_t *spa, pool_scrub_cmd_t flag);
 

lib/libzfs/libzfs.abi

@@ -6482,6 +6482,7 @@
       <enumerator name='POOL_SCRUB_PAUSE' value='1'/>
       <enumerator name='POOL_SCRUB_FROM_LAST_TXG' value='2'/>
       <enumerator name='POOL_SCRUB_FLAGS_END' value='3'/>
+      <enumerator name='POOL_SCRUB_THOROUGH' value='8'/>
     </enum-decl>
     <typedef-decl name='pool_scrub_cmd_t' type-id='a1474cbd' id='b51cf3c2'/>
     <enum-decl name='zpool_errata' id='d9abbf54'>