ZPOOL-SCRUB(8)

✨ zpool-scrub(8) — the glow-up your pool deserves ✨

okay bestie, sit down, grab a strawberry 🍓, because we're talking about zpool-scrub — the zpool subcommand that begins or resumes scrub of ZFS storage pools. it's giving "spa day for your disks" and honestly? iconic.

---

🌸 SYNOPSIS 🌸

zpool scrub [-e |-p | -s| -C][-w] [-S date] [-E date] -a|pool…

that's the whole vibe. yes the spacing is exactly like that, don't come for me 💅

---

🦋 DESCRIPTION 🦋

so what does a scrub even do? it begins a scrub or resumes a paused scrub. the scrub goes through literally all data in the pools you named and verifies that it checksums correctly. and for replicated devices — that's your mirror, raidz, or draid setups — ZFS automatically repairs any damage it finds during the scrub. like, no cap, it just fixes it. the zpool status command reports the progress of the scrub and summarizes the results of the scrub upon completion. main character behavior fr fr 👑

Scrubbing and resilvering are very similar operations — they're cousins, lowkey. the difference is that resilvering only examines data that ZFS knows to be out of date (think: when you attach a new device to a mirror or replace an existing device), whereas scrubbing examines all data to discover silent errors due to hardware faults or disk failure. one is a quick touch-up, the other is a full facial. 🧖‍♀️

When scrubbing a pool with encrypted filesystems, the keys do not need to be loaded. however. 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. so like, you'll see the problem but not its government name 😭

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

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. it's organizing before the party, basically. 🎀

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

Note that, due to changes in pool data on a live system, it is possible for scrubs to progress slightly beyond 100% completion. during this period, no completion time estimate will be provided. yeah she's overachieving, leave her alone 💀

---

💖 OPTIONS 💖

• -a, --all — begin, pause, stop 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. it's a lot of energy all at once, bestie.
• -s — stop scrubbing. 🛑
• -p — pause scrubbing. 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 or zpool scrub -e again. she's holding her place in line 🫶
• -w — wait until scrub has completed before returning. she will not leave until the job is done.
• -e — only scrub files with known data errors as reported by zpool status -v. the pool must have been scrubbed at least once with the head_errlog feature enabled to use this option. error scrubbing cannot be run simultaneously with regular scrubbing or resilvering, nor can it be run when a regular scrub is paused. targeted, focused, no distractions ✨
• -C — continue scrub from last saved txg (see zpool last_scrubbed_txg property). picking up right where you left off.
• -S date, -E date — allows specifying the date range for blocks created between these dates.
  • -S defines a start date. if not specified, scrubbing begins from the start of the pool's existence.
  • -E 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. if the time was moved backward manually the data range may become inaccurate. 🕰️

---

🌈 EXAMPLES 🌈

Example 1

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. look at her go 💅

---

⭐ PERIODIC SCRUB ⭐

On machines using systemd, scrub timers can be enabled on per-pool basis. weekly and monthly timer units are provided. set it and forget it, honestly the dream 🌙

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

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

On Debian systems, a periodic scrub is additionally run for all online pools on the second Sunday of each month, without enabling any per-pool timer. whether a given pool is scrubbed is controlled by the org.debian:periodic-scrub user property on the pool's root dataset, which accepts auto (the default, same as unset), enable, or disable. see /usr/share/doc/zfsutils-linux/README.Debian for details. 🔍

---

👑 SEE ALSO 👑

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

go read those next, bestie, iykyk 📚

---

okay that's the whole page, and that's the vibe check passed ✅ this one ships with OpenZFS, dated August 6, 2025 — so if anyone asks where you learned all this, you can tell them you got it straight from the source. scrub responsibly, hydrate, and remember: your pool is only as healthy as its last scan. bye bestie 💜🦋✨