How to Use Btrfs Scrub?

The Btrfs filesystem is a multi-device filesystem that has built-in support for RAID. In a multi-device Btrfs filesystem or RAID, the data/metadata blocks may be stored in one or more storage devices. The Btrfs scrub tool will read all the data/metadata blocks from all the storage devices added to a Btrfs filesystem or RAID and find all the corrupted data/metadata blocks. Once the corrupted data/metadata blocks are found, the Btrfs scrub tool will automatically repair those corrupted data/metadata blocks if possible.

In a multi-device Btrfs filesystem or Btrfs RAID, depending on the filesystem configuration, there may be multiple copies of the data/metadata blocks stored in different locations of the storage devices added to the Btrfs filesystem. When the Btrfs scrub tool finds a corrupted data/metadata block, it searches all the storage devices added to the Btrfs filesystem for duplicate copies of that data/metadata block. Once a duplicate copy of that data/metadata block is found, the corrupted data/metadata block is overwritten with the correct data/metadata block. This is how the Btrfs scrub tool repairs corrupted data/metadata blocks in a multi-device Btrfs filesystem or Btrfs RAID.

In this article, I am going to show you how to use the Btrfs scrub tool to find and repair corrupted data/metadata blocks in a multi-device Btrfs filesystem or Btrfs RAID. So, let’s get started.

Abbreviations

RAID – Redundant Array of Inexpensive/Independent Disks

GB – Gigabyte

Prerequisites

To follow this article, you need to have a working multi-device Btrfs filesystem or a Btrfs RAID.

I have created a Btrfs RAID in RAID-1 configuration (mounted on the /data directory) using 4 storage devices sdb, sdc, sdd, and sde, as you can see in the screenshot below. I will be using this Btrfs RAID for the Btrfs scrub demonstration in this article.

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_1.jpg" data-lazy- height="731" src="data:image/svg xml,” width=”691″>

If you need any assistance on installing the Btrfs filesystem on Ubuntu, check my article Install and Use Btrfs on Ubuntu 20.04 LTS.

If you need any assistance on installing the Btrfs filesystem on Fedora, check my article Install and Use Btrfs on Fedora 33.

If you need any assistance in creating a Btrfs RAID, check my article How to Setup Btrfs RAID.

Generating Dummy Files on the Btrfs Filesystem

To show you how the Btrfs scrub tool works, we need to generate some random files to fill up the Btrfs filesystem. Let’s create a shell script that does just that.

Create a new shell script genfiles.sh in the /usr/local/bin/ directory as follows:

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_2.jpg" data-lazy- height="86" src="data:image/svg xml,” width=”685″>

Type in the following lines of codes in the genfiles.sh shell script.

Once you’re done, press X followed by Y and to save the genfiles.sh shell script.

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_3.jpg" data-lazy- height="434" src="data:image/svg xml,” width=”831″>

The genfiles.sh shell script runs an infinite while loop.

The following line generates a UUID using the uuidgen command and stores the UUID in the FILENAME variable.

<img alt="" data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_4.jpg" height="34" src="data:image/svg xml,” width=”244″>

The following line prints a message on the console before the file FILENAME is generated.

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_5.jpg" data-lazy- height="36" src="data:image/svg xml,” width=”356″>

The following line generates a new random file FILENAME using the dd command. The file will be 256 MB in size.

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_6.jpg" data-lazy- height="35" src="data:image/svg xml,” width=”779″>

The following line prints a message on the console after the file FILENAME is generated.

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_7.jpg" data-lazy- height="34" src="data:image/svg xml,” width=”338″>

Add execute permission to the genfiles.sh shell script as follows:

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_8.jpg" data-lazy- height="101" src="data:image/svg xml,” width=”703″>

The genfiles.sh shell script should now be accessible as any other commands.

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_9.jpg" data-lazy- height="143" src="data:image/svg xml,” width=”539″>

Let’s generate some random files in the Btrfs RAID mounted in the /data directory.

Navigate to the /data directory where the Btrfs RAID is mounted as follows:

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_10.jpg" data-lazy- height="115" src="data:image/svg xml,” width=”533″>

As you can see, there are no files available in my Btrfs RAID at the moment.

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_11.jpg" data-lazy- height="136" src="data:image/svg xml,” width=”549″>

To generate some random files in the current working directory (/data directory in this case), run the genfiles.sh shell script as follows:

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_12.jpg" data-lazy- height="84" src="data:image/svg xml,” width=”554″>

The genfiles.sh shell script should start generating random files in the /data directory.

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_13.jpg" data-lazy- height="281" src="data:image/svg xml,” width=”690″>

The genfiles.sh script is generating random files. Let the script run for a couple of minutes, so it fills up about 2-3 GB of disk space of the Btrfs RAID.

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_14.jpg" data-lazy- height="484" src="data:image/svg xml,” width=”822″>

When you want to stop the genfiles.sh shell script, press C.

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_15.jpg" data-lazy- height="496" src="data:image/svg xml,” width=”843″>

As you can see, some random files are generated in the Btrfs RAID.

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_16.jpg" data-lazy- height="554" src="data:image/svg xml,” width=”822″>

I have generated about 13 GB of random files in the Btrfs RAID mounted in the /data directory, as you can see in the screenshot below.

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_17.jpg" data-lazy- height="139" src="data:image/svg xml,” width=”544″>

Working with the Btrfs Scrub Tool

In this section, I am going to show you how to use the Btrfs scrub tool. Let’s get started.

You can start the scrub process on the Btrfs filesystem mounted on the /data directory with the following command:

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_18.jpg" data-lazy- height="92" src="data:image/svg xml,” width=”587″>

A Btrfs scrub process should be started on the Btrfs filesystem mounted on the /data directory.

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_19.jpg" data-lazy- height="138" src="data:image/svg xml,” width=”841″>

You can see the status of the Btrfs scrub process running on the Btrfs filesystem mounted on the /data directory as follows:

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_20.jpg" data-lazy- height="80" src="data:image/svg xml,” width=”601″>

As you can see, the Btrfs scrub process is still running.

Scrubbing a Btrfs filesystem or Btrfs RAID that has a lot of files will take a long time to complete.

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_21.jpg" data-lazy- height="342" src="data:image/svg xml,” width=”690″>

Once the Btrfs scrub process is complete, the status should be changed to finished, as you can see in the screenshot below.

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_22.jpg" data-lazy- height="268" src="data:image/svg xml,” width=”591″>

You can also see the Btrfs scrub status for each of the storage devices added to the Btrfs filesystem (mounted in the /data directory) separately as follows:

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_23.jpg" data-lazy- height="765" src="data:image/svg xml,” width=”670″>

I have told you that the Btrfs scrub process takes a long time to complete on a big Btrfs filesystem. One big advantage of the Btrfs scrub tool is that its process can be paused and resumed at any time.

Let’s see how to pause and resume a Btrfs scrub process.

First, start a new Btrfs scrub process on the Btrfs filesystem mounted in the /data directory as follows:

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_24.jpg" data-lazy- height="127" src="data:image/svg xml,” width=”840″>

To cancel or pause the Btrfs scrub process that is currently running on the Btrfs filesystem mounted on the /data directory, run the following command:

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_25.jpg" data-lazy- height="78" src="data:image/svg xml,” width=”589″>

The running Btrfs scrub process should be canceled or paused.

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_26.jpg" data-lazy- height="134" src="data:image/svg xml,” width=”589″>

As you can see, the Btrfs scrub status is aborted. So, the Btrfs scrub process is not running anymore.

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_27.jpg" data-lazy- height="267" src="data:image/svg xml,” width=”690″>

To resume the Btrfs scrub process that you’ve canceled or paused, run the following command:

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_28.jpg" data-lazy- height="86" src="data:image/svg xml,” width=”580″>

The Btrfs scrub process should be resumed.

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_29.jpg" data-lazy- height="132" src="data:image/svg xml,” width=”791″>

As you can see, the Btrfs scrub status is now running. So, the Btrfs scrub process is resumed.

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_30.jpg" data-lazy- height="327" src="data:image/svg xml,” width=”590″>

After the Btrfs scrub process is complete, the Btrfs scrub status should be changed to finished.

<img alt="" data-lazy- data-lazy-src="https://kirelos.com/wp-content/uploads/2021/01/echo/How-to-Use-Btrfs-Scrub_31.jpg" data-lazy- height="273" src="data:image/svg xml,” width=”612″>

Conclusion

In this article, I have shown you how to work with the Btrfs scrub tool to find and fix corrupted data/metadata blocks of a Btrfs multi-device filesystem or RAID. I have shown you how to cancel/pause and resume a Btrfs scrub process once it’s started as well.