zpool-scrub.8

ZPOOL-SCRUB(8) System Manager's Manual ZPOOL-SCRUB(8)

zpool-scrub — begin or resume scrub of ZFS storage pools

zpool scrub [-w] [-t] [-C | [-S date] [-E date]] -a|pool…

zpool scrub -e [-w] -a|pool…

zpool scrub -p -a|pool…

zpool scrub -s -a|pool…

Begins a scrub or resumes a paused scrub. A normal scrub examines all data in the specified pools and verifies each block's checksum. A thorough scrub additionally decrypts and/or decompresses blocks as they are read. For replicated (mirror, raidz, or draid) devices, ZFS automatically repairs any damage discovered during the scrub. The zpool status command reports the progress of the scrub and summarizes the results of the scrub upon completion.

Scrubbing and resilvering are very similar operations. The difference is that resilvering only examines data that ZFS knows to be out of date (for example, when attaching a new device to a mirror or replacing an existing device), whereas scrubbing examines all data to discover silent errors due to hardware faults or disk failure.

When scrubbing a pool with encrypted filesystems the keys do not need to be loaded for ordinary checksum verification but are needed for thorough scrub (see -t) below.

If the keys are not loaded and an unrepairable checksum error is detected the file name cannot be included in the zpool status -v verbose error report.

Because scrubbing and resilvering are I/O-intensive operations, ZFS only allows one at a time.

A scrub is split into two parts: metadata scanning and block scrubbing. The metadata scanning sorts blocks into large sequential ranges which can then be read much more efficiently from disk when issuing the scrub I/O.

If a scrub is paused, the zpool scrub resumes it. If a resilver is in progress, ZFS does not allow a scrub to be started until the resilver completes.

Note that, due to changes in pool data on a live system, it is possible for scrubs and resilvers to progress beyond 100% completion. During this period, no completion time estimate will be provided.

, --all
Begin, pause -p, or stop -s, scrub on all pools. Initiating scrubs on multiple pools can put considerable load and memory pressure on the system, so this operation should be performed with caution.
Stop scrubbing. Cannot be combined with other options except -a.
Pause scrubbing. Cannot be combined with other options except -a. Scrub pause state and progress are periodically synced to disk. If the system is restarted or pool is exported during a paused scrub, even after import, scrub will remain paused until it is resumed. Once resumed the scrub will pick up from the place where it was last checkpointed to disk. To resume a paused scrub issue zpool scrub. The scrub resumes in the same mode (normal or thorough) it had when it started. To resume paused error scrub, issue zpool scrub -e.
Wait until scrub has completed before returning.
Only scrub files with known data errors as reported by zpool status -v. The pool must have been scrubbed at least once with the feature enabled to use this option. Error scrubbing cannot be run simultaneously with other scrubbing or resilvering, nor can it be run when a scrub is paused. This option cannot be combined with -C, -p, -s, or -t.
Continue scrub from last saved txg (see zpool property). Cannot be combined with -S, -E, -e, -p, or -s. May be combined with thorough scrub (-t).
Thorough scrub. Will cause scrub to decrypt and decompress blocks it reads so that it will catch the rare type of corruption where the checksum matches the data, but decryption and/or decompression fails. For encrypted datasets keys have to be loaded in order to perform thorough scrub. If keys are not loaded or unloaded during a thorough scrub the scrub will revert to doing a normal scrub for the encrypted blocks with key(s) unloaded. Cannot be combined with -e, -p, or -s. May be combined with -a, -w, -C or start/end date options (-S -/ -E).

If a thorough scrub is paused, resuming with zpool scrub (with or without) -t continues as a thorough scrub. Resuming a paused normal scrub with -t will fail; use zpool scrub without -t.

date, -E date
Allows specifying the date range for blocks created between these dates.
  • Defines a start date. If not specified, scrubbing begins from the start of the pool's existence.
  • Defines an end date. If not specified, scrubbing continues up to the most recent data.
The provided date should be in the format: “YYYY-MM-DD HH:MM”. Where:
  • “YYYY” is the year.
  • “MM” is the numeric representation of the month.
  • “DD” is the day of the month.
  • “HH” is the hour.
  • “MM” is the minutes.
The hour and minutes parameters can be omitted. The time should be provided in machine local time zone. Specifying dates prior to enabling this feature will result in scrubbing starting from the date the pool was created. Large or discontinuous changes to the system clock (forward or backward) can skew how the start and/or end dates map to pool transaction groups. As a result, the scrub may not cover the intended dates.

Cannot be combined with -C.

Status of pool with ongoing scrub:

# zpool status
  ...
  scan: scrub in progress since Sun Jul 25 16:07:49 2021
        403M / 405M scanned at 100M/s, 68.4M / 405M issued at 10.0M/s
        0B repaired, 16.91% done, 00:00:04 to go
  ...

Where metadata which references 403M of file data has been scanned at 100M/s, and 68.4M of that file data has been scrubbed sequentially at 10.0M/s.

On machines using systemd, scrub timers can be enabled on per-pool basis. weekly and monthly timer units are provided.

systemctl enable zfs-scrub-weekly@rpool.timer --now
systemctl enable zfs-scrub-monthly@otherpool.timer --now

systemd.timer(5), zpool-iostat(8), zpool-resilver(8), zpool-status(8)

May 1, 2026 Debian