How to use the command `btrfs scrub` (with examples)

Btrfs is a modern copy-on-write (CoW) filesystem for Linux. The btrfs scrub command is used to verify the integrity of data stored on Btrfs filesystems. In this article, we will explore different use cases of the btrfs scrub command and how to use them effectively.

Use case 1: Start a scrub

Code:

sudo btrfs scrub start path/to/btrfs_mount

Motivation: Starting a scrub is essential to verify the integrity of data stored on Btrfs filesystems. By running this command, you initiate a scrub process that checks the data and metadata against checksums, repairing any inconsistencies it finds.

Explanation:

• sudo: It is used to execute the command as a superuser or with administrative privileges.
• btrfs scrub start: This command starts a scrub process on the specified Btrfs filesystem.
• path/to/btrfs_mount: This argument represents the mount point of the Btrfs filesystem to be scrubbed.

Example output:

Scrub started on '/path/to/btrfs_mount', pid: 12345, status: running

Use case 2: Show the status of an ongoing or last completed scrub

Code:

sudo btrfs scrub status path/to/btrfs_mount

Motivation: Checking the status of an ongoing or last completed scrub provides valuable information about the progress and results of the scrub process. It helps to ensure that the data integrity verification is being performed correctly.

Explanation:

• sudo: It is used to execute the command as a superuser or with administrative privileges.
• btrfs scrub status: This command displays the status of an ongoing or last completed scrub.
• path/to/btrfs_mount: This argument represents the mount point of the Btrfs filesystem being scrubbed.

Example output:

Scrub started on:       01/01/2023 12:00
Scrub finished:         01/01/2023 13:00
Status:                 finished
Duration:               1 hour

Use case 3: Cancel an ongoing scrub

Code:

sudo btrfs scrub cancel path/to/btrfs_mount

Motivation: Sometimes, it may be necessary to cancel an ongoing scrub process due to various reasons, such as system maintenance or user intervention. This command allows you to stop the scrub process in such scenarios.

Explanation:

• sudo: It is used to execute the command as a superuser or with administrative privileges.
• btrfs scrub cancel: This command cancels an ongoing scrub process.
• path/to/btrfs_mount: This argument represents the mount point of the Btrfs filesystem with the ongoing scrub.

Example output:

Scrub on '/path/to/btrfs_mount' canceled successfully

Use case 4: Resume a previously cancelled scrub

Code:

sudo btrfs scrub resume path/to/btrfs_mount

Motivation: If a scrub process was canceled earlier, it can be resumed using this command. Resuming a previously cancelled scrub allows you to continue the data integrity verification without starting from scratch.

Explanation:

• sudo: It is used to execute the command as a superuser or with administrative privileges.
• btrfs scrub resume: This command resumes a previously cancelled scrub process.
• path/to/btrfs_mount: This argument represents the mount point of the Btrfs filesystem with the cancelled scrub.

Example output:

Scrub on '/path/to/btrfs_mount' resumed successfully

Use case 5: Start a scrub, but wait until the scrub finishes before exiting

Code:

sudo btrfs scrub start -B path/to/btrfs_mount

Motivation: In some situations, it is essential to wait until the scrub process finishes before exiting the command prompt or script. This command ensures that the command prompt or script remains active until the scrub process is completed.

Explanation:

• sudo: It is used to execute the command as a superuser or with administrative privileges.
• btrfs scrub start: This command starts a scrub process on the specified Btrfs filesystem.
• -B: This argument tells the command to wait for the scrub process to finish before exiting.
• path/to/btrfs_mount: This argument represents the mount point of the Btrfs filesystem to be scrubbed.

Example output:

Scrub started on '/path/to/btrfs_mount', pid: 12345, status: running

(No output until the scrub finishes)

Use case 6: Start a scrub in quiet mode (does not print errors or statistics)

Code:

sudo btrfs scrub start -q path/to/btrfs_mount

Motivation: In certain scenarios, such as when running the command in a script or when only interested in the final result, it might be preferred to suppress the printing of errors or statistics during the scrub process. This command starts a scrub in quiet mode, reducing the amount of output produced.

Explanation:

• sudo: It is used to execute the command as a superuser or with administrative privileges.
• btrfs scrub start: This command starts a scrub process on the specified Btrfs filesystem.
• -q: This argument enables quiet mode, which suppresses the printing of errors or statistics.
• path/to/btrfs_mount: This argument represents the mount point of the Btrfs filesystem to be scrubbed.

Example output:

(No output until the scrub finishes)

Conclusion:

The btrfs scrub command is a powerful tool for ensuring the integrity of data stored on Btrfs filesystems. By understanding and utilizing its various options, you can initiate scrubs, check their status, cancel or resume them, wait until they finish, and control the verbosity of output during the process. Regularly running scrubs is recommended to maintain the data integrity and reliability of Btrfs filesystems.