You can initiate a check of the entire file system by triggering a file system scrub job. The scrub job runs in the background by default and scans the entire file system for integrity. It automatically attempts to report and repair any bad blocks that it finds along the way. Instead of going through the entire disk drive, the scrub job deals only with data that is actually allocated. Depending on the allocated disk space, this is much faster than performing an entire surface scan of the disk.
Scrubbing involves reading all the data from all the disks and verifying checksums. If any values are not correct, the data can be corrected by reading a good copy of the block from another drive. The scrubbing code also scans on read automatically. It is recommended that you scrub high-usage file systems once a week and all other file systems once a month.
The following is a list of the available btrfs scrub commands:
# btrfs scrub
usage: btrfs scrub [command] [options] [path]|[device]
btrfs scrub start [-BdqrRf] [-c ioprio_class -n ioprio_classdata] [path]|[device]
Start a new scrub. If a scrub is already running, the new one fails.
btrfs scrub cancel [path]|[device]
Cancel a running scrub
btrfs scrub resume [-BdqrR] [-c ioprio_class -n ioprio_classdata] [path]|[device]
Resume previously canceled or interrupted scrub
btrfs scrub status [-dR] [path]|[device]
Show status of running or finished scrub
verify checksums of data and metadata
btrfs scrub Utility: Examples
Use the btrfs scrub start command to start a scrub on all the devices of a file system or on a single device. The syntax is as follows:
# btrfs scrub start [-BdqrR] [-c ioprio_class ...
Description of options:
| Option | Description |
|---|---|
| -B | Do not run in the background and print statistics when finished. |
| -d | Print separate statistics for each device of the file system. This option is used in conjunction with the -B option. |
| -q | Run in quiet mode, omitting error messages and statistics. |
| -r | Run in read-only mode, not correcting any errors. |
| -R | Raw print mode. Print full data instead of summary. |
| -c ioprio_class | Set IO priority class (see ionice man page). |
| -n ioprio_classdata | Set IO priority classdata (see ionice man page). |
Starting btrfs scrub
The following example starts a scrub on the Btrfs file system that is mounted on /btrfs.
# btrfs scrub start /btrfs scrub started on /btrfs, fsid ba60ac96-1628-4656-b68b-c7327ff49179 (pid=11164)
Use the btrfs scrub status command to get the status of a scrub job. One option is available:
-d– Print separate statistics for each device of the file system.
Below is a btrfs scrub status command example on a healthy filesystem. In case of a corrupted filesystem, you would see corrected errors in the output.
# btrfs scrub status /btrfs scrub status for ba60ac96-1628-4656-b68b-c7327ff49179 scrub started at Fri Mar 30 14:29:47 2018 and finished after 00:00:02 total bytes scrubbed: 325.29MiB with 0 errors
With the “-d” option in the above command, you can get a per-device level status as shown in the example below.
# btrfs scrub status /btrfs -d scrub status for ba60ac96-1628-4656-b68b-c7327ff49179 scrub device /dev/sda (id 1) history scrub started at Fri Mar 30 14:29:47 2018 and finished after 00:00:02 total bytes scrubbed: 325.29MiB with 0 errors
Canceling/Resuming a btrfs scrub job
You can also cancel a running scrub job. Progress is saved in the scrub progress file and you can resume scrubbing later. To cancel a scrub:
With the “-d” option in the above command, you can get a per-device level status as shown in the example below.
# btrfs scrub cancel /btrfs
To resume a canceled or interrupted scrub job:
# btrfs scrub resume /btrfs
The scrub resume command has the same options as the scrub start command. Btrfs stores the last two minutes, at 30-second intervals, of root ID generations. Btrfs continues to keep rolling these generations, even if there are no changes in the file system.
If a scrub does not correct errors, you can use the following mount option to roll back to a known good B-tree, given that the rest of the tree is available because of copy-on-write:
# mount –o recovery /dev/sda /btrfs
