btrfs-scrub

Start a scrub

$ sudo btrfs scrub start [path/to/btrfs_mount]

$ sudo btrfs scrub status [path/to/btrfs_mount]

$ sudo btrfs scrub cancel [path/to/btrfs_mount]

$ sudo btrfs scrub resume [path/to/btrfs_mount]

$ sudo btrfs scrub start -B [path/to/btrfs_mount]

$ sudo btrfs scrub start [[-q|--quiet]] [path/to/btrfs_mount]

btrfs scrub {start|cancel|status|resume} [options] <path|device>

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)

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.

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.

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.

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.

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.

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.

btrfs(8), btrfs-check(8), btrfs-balance(8), btrfs-device(8)