LinuxCommandLibrary

btrfs-scrub

Verify and repair Btrfs filesystem integrity

TLDR

Start a scrub

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

Show the status of an ongoing or last completed scrub
$ sudo btrfs scrub status [path/to/btrfs_mount]
copy

Cancel an ongoing scrub
$ sudo btrfs scrub cancel [path/to/btrfs_mount]
copy

Resume a previously cancelled scrub
$ sudo btrfs scrub resume [path/to/btrfs_mount]
copy

Start a scrub, but do not put the program in the [B]ackground
$ sudo btrfs scrub start -B [path/to/btrfs_mount]
copy

Start a scrub in quiet mode (does not print errors or statistics)
$ sudo btrfs scrub start [[-q|--quiet]] [path/to/btrfs_mount]
copy

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

Copied to clipboard