btrfs-scrub
Verify and repair Btrfs filesystem integrity
TLDR
Start a scrub
Show the status of an ongoing or last completed scrub
Cancel an ongoing scrub
Resume a previously cancelled scrub
Start a scrub, but do not put the program in the [B]ackground
Start a scrub in quiet mode (does not print errors or statistics)
SYNOPSIS
btrfs scrub {start|cancel|status|resume} [options] <path|device>
PARAMETERS
start
Starts a scrub on the specified filesystem or device. If a scrub is already running, it will report an error unless --force is used.
cancel
Cancels a running scrub for the specified filesystem or device.
status
Shows the status of a running scrub or the results of the last completed scrub for the specified filesystem or device.
resume
Resumes a previously paused or interrupted scrub for the specified filesystem or device.
-B, --background
Run the scrub in the background. (For start and resume)
-d, --dry-run
Do not repair anything, just report what would be repaired. (For start and resume)
-f, --force
Force a scrub to start even if one is already running. (For start only)
-r, --rescan-devices
Rescan the devices that are part of the filesystem. This is useful if devices have been added or removed. (For start and resume)
-R, --read-only
Do not write anything to the device. This implies --dry-run but also means no progress will be saved for resume. (For start and resume)
DESCRIPTION
The btrfs scrub command initiates an online scan of a Btrfs filesystem. During this scan, all data and metadata blocks are read, and their checksums are verified. If a checksum mismatch is detected for data blocks and the filesystem uses a redundant RAID profile (like RAID1, RAID1C3, RAID1C4, RAID5, or RAID6), btrfs scrub attempts to repair the corrupted blocks using a good copy from another device.
This operation helps to detect and mitigate bitrot or silent data corruption. It's a non-destructive process and can be run on a mounted, active filesystem. Although it can be I/O intensive, it's designed to run in the background and can be paused, resumed, or canceled. Regularly scrubbing your Btrfs filesystems is a crucial part of maintaining data integrity.
CAVEATS
Key Caveats and Limitations:
- A scrub operation can be I/O intensive and might impact system performance, especially on busy systems. It's recommended to run scrubs during off-peak hours or with the --background option.
- Scrub only repairs data blocks if the filesystem is configured with a redundant RAID profile (e.g., RAID1, RAID1C3, RAID1C4, RAID5, RAID6). For single disk or RAID0 profiles, it will detect corruption but cannot repair it automatically.
- It requires the Btrfs filesystem to be mounted.
- btrfs scrub primarily checks for data integrity by verifying checksums. It is not a replacement for btrfs check, which verifies and repairs the filesystem's structural consistency offline.
- The progress and speed of the scrub can be influenced by system load and I/O scheduler settings.
SCRUB VS. CHECK
It's important to differentiate between btrfs scrub and btrfs check. btrfs scrub is an online operation that verifies data and metadata checksums on an active, mounted filesystem and attempts to repair corrupted blocks if redundancy is available. In contrast, btrfs check is an offline tool used to verify and potentially repair the structural integrity of a unmounted Btrfs filesystem. They serve different but complementary purposes in filesystem maintenance.
PERFORMANCE IMPACT
While designed to run in the background, btrfs scrub can still consume significant I/O bandwidth and CPU resources. Users may notice a performance degradation during a scrub, especially on systems with limited I/O throughput or during periods of high disk activity. The --background option helps mitigate this by running the scrub with a lower I/O priority, but it does not eliminate the resource consumption entirely.
PROGRESS MONITORING
The progress of an active scrub can be monitored using the btrfs scrub status command. This command provides information such as the total data scrubbed, number of errors found, and estimated time remaining. For long-running scrubs, it's a valuable tool to track its progress.
HISTORY
The btrfs scrub command is an integral part of the btrfs-progs user-space utilities, which provide the tools for managing Btrfs filesystems. It has been available since the early development phases of Btrfs, reflecting the filesystem's strong focus on data integrity and self-healing capabilities. Its development has mirrored the ongoing evolution of the Btrfs filesystem itself, with continuous improvements in performance, reliability, and feature set over the years.
SEE ALSO
btrfs(8), btrfs-check(8), btrfs-balance(8), btrfs-device(8)