Tools: Your Btrfs Before It Scrubs You: Practical `btrfs scrub` + systemd timer Scrub
What btrfs scrub actually checks
What scrub does not do
When scrub can repair corruption, and when it cannot
The practical cadence: monthly is the documented default
Manual health-check workflow first
1) Make sure the target is actually Btrfs
2) Run a foreground scrub
3) Re-check the last recorded status
Understanding the result
Automate it with systemd
Service unit: /etc/systemd/system/[email protected]
Timer unit: /etc/systemd/system/[email protected]
Enable it for /
Verify the automation
What about I/O impact?
A minimal recovery-minded checklist
The main point
References If you run Btrfs and never schedule btrfs scrub, you are skipping one of the filesystem's most useful maintenance tools. Scrub is not glamorous. It does not make your box faster. It will not clean up space. But it does walk your filesystem, verify checksums on data and metadata, and, when redundant copies exist, repair corrupted blocks from a good copy. That is exactly the sort of quiet maintenance you want happening before a bad block turns into a bad day. According to btrfs-scrub(8), scrub reads filesystem data and metadata, verifies checksums, and validates all copies of redundant block-group profiles.
If a corrupted block has another valid copy available, scrub can repair the bad copy automatically. That means scrub is especially valuable on Btrfs filesystems that use redundancy for metadata and, where configured, for data too. A simple manual run looks like this: The -B flag keeps the command in the foreground and prints stats when it finishes, which is useful for manual checks and for one-shot troubleshooting. If you want per-device statistics on a multi-device filesystem, add -d: btrfs-scrub(8) is very explicit: scrub is not a filesystem checker, and it does not repair structural filesystem damage.It checks checksums on data and tree blocks, but it is not a replacement for btrfs check. So think about the tools like this: If you remember only one sentence from this article, make it this one: scrub is preventive integrity maintenance, not a general-purpose rescue tool. Scrub can repair corrupted blocks only if there is another valid copy to repair from. In practice, that means: Scrub is still worth running on single-device systems because detection matters.Finding checksum mismatches early is much better than learning about them during a restore, upgrade, or database read months later. The Btrfs scrub docs recommend running it manually or through a periodic system service, and call monthly the recommended interval.That is a sensible default for most Linux systems. If your box stores frequently changing important data, you can run it more often.If it is archival or lightly used, monthly is still a strong baseline. Before automating anything, I like to confirm the basics manually. If you use multiple Btrfs mountpoints, replace / with the mount you actually want to scrub. A healthy result typically ends with something like: Useful fields to look at: If you want raw counters for deeper debugging: If errors are present, btrfs-scrub(8) documents a few counters worth watching: If you see uncorrectable errors, stop treating the system as fully healthy.That does not automatically mean catastrophic loss, but it does mean you should investigate the affected device, verify backups, and inspect the filesystem layout and redundancy assumptions. Also note the documented exit codes: That makes it easy to wire alerting or log review around the command later. A monthly timer is a clean fit here. systemd.timer(5) documents that a timer activates the matching service by default, so [email protected] can activate [email protected] automatically.It also documents Persistent=true, which is useful for catch-up behavior if the machine was off during the scheduled time. I prefer a template unit so you can reuse the same service for /, /home, or any other Btrfs mountpoint. A few reasons I like this version: Because this is a template unit, systemd needs an escaped instance name for mount paths.For the root filesystem, use: Why -?Because / is escaped by systemd to -. If you want to see the escape result explicitly: For /home, the instance would be: And you would enable: First, inspect the timer: Then trigger the service manually once: And inspect the logs: Finally, confirm the recorded scrub status: The Btrfs docs note that scrub state is recorded under /var/lib/btrfs/, so status still has something useful to show even after the active run ends. This is where people get tripped up by old assumptions. Older guidance often says scrub runs with idle I/O priority and therefore should not interfere much with normal workloads.That can be true, but current docs are more careful: I/O priority behavior is scheduler-dependent.The Btrfs docs explicitly warn that ionice-style behavior may not work as expected on all schedulers, and the Linux kernel I/O-priority docs say support is scheduler-dependent. Do not blindly trust decade-old blog posts about ionice and call it done. If scrub reports corrected or uncorrectable errors, do these next: This is also where scrub and hardware monitoring complement each other nicely.SMART/NVMe telemetry tells you about the device.Scrub tells you whether the filesystem's checksummed data is staying readable and consistent. If you chose Btrfs, use the maintenance features that make Btrfs worth choosing. A monthly scrub is low drama, easy to automate, and one of the clearest examples of boring Linux hygiene paying off exactly when you need it. Not every integrity problem can be repaired.
But catching corruption early, and automatically repairing it when redundancy exists, is a lot better than finding out by accident later. Templates let you quickly answer FAQs or store snippets for re-use. Hide child comments as well For further actions, you may consider blocking this person and/or reporting abuse
