Phenquestions
Once you've created a Btrfs RAID, you can add more storage devices to the RAID to expand the RAID. But, once you have added more storage devices to the RAID, Btrfs won't spread the existing data/metadata/system-data to the new storage devices automatically. So, you may not get the desired throughput (read/write speed) out of the RAID, and it may not be able to populate the new storage devices with the required redundant data. So, the RAID array may fail to survive the desired number of drive failures.
To solve these problems, the Btrfs filesystem provides a built-in balancing tool. The Btrfs balance utility will spread the data/metadata/system-data of the existing storage devices of the RAID to the newly added storage devices.
In this article, I am going to show you how to use the Btrfs balance utility to spread the data/metadata/system-data of the existing storage devices of the RAID to the newly added storage devices. So, let's get started!
Abbreviations
RAID - Redundant Array of Inexpensive/Independent Disks
MB - Megabyte
GB - Gigabyte
Prerequisites
To follow this article, you need to have a working Btrfs RAID or multi-device setup.
I have created a Btrfs RAID in RAID-0 configuration using 4 storage devices sdb, sdc, sdd, and sde.
As you can see, the Btrfs filesystem allocated 1 GB of disk space for data1 256 MB of disk space for metadata2, and 4 MB of disk space for system-data3 from each of the storage devices in the RAID.
About 18.75 GB out of 20 GB is still unallocated4 from each of the storage devices of the RAID.
$ sudo btrfs filesystem usage /data
Writing a Script to Generate Random Files
To show you how the Btrfs balance utility 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:
$ sudo nano /usr/local/bin/genfiles.sh
Type in the following lines of codes in the genfiles.sh shell script.
#!/bin/bashwhile true
do
FILENAME=$(uuidgen)
echo "[Creating] $FILENAME"
dd if=/dev/random of=$FILENAME bs=1M count=256 status=progress
echo "[Created] $FILENAME"
done
Once you're done, press
The genfiles.sh shell script runs an infinite while loop.
while truedo
# other codes
done
The following line generates a UUID using the uuidgen command and stores the UUID in the FILENAME variable.
The following line prints a message on the console before the file FILENAME is generated.
The following line generates a new random file FILENAME using the dd command. The file will be 256 MB in size.
The following line prints a message on the console after the file FILENAME is generated.
Add execute permission to the genfiles.sh shell script as follows:
$ sudo chmod +x /usr/local/bin/genfiles.sh
The genfiles.sh shell script should now be accessible as any other commands.
$ which genfiles.sh
Generating Random Files in the Btrfs Filesystem
We want to generate random files in the Btrfs RAID. Let's say, the Btrfs RAID is mounted on the /data directory.
Navigate to the /data directory where the Btrfs RAID is mounted as follows:
$ cd /data
As you can see, there are no files available in my Btrfs RAID at the moment.
$ ls -lh
To generate some random files in the current working directory (/data directory in this case), run the genfiles.sh shell script as follows:
$ sudo genfiles.sh
The genfiles.sh shell script should start generating random files in the /data directory.
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.
When you want to stop the genfiles.sh shell script, press 
As you can see, some random files are generated in the Btrfs RAID.
$ ls -lh
As you can see, the Btrfs RAID allocated 2 GB from each of the storage devices added to the RAID. Previously the Btrfs RAID allocated 1 GB from each of the storage devices added to the RAID.
The unallocated disk space has been reduced from 18.75 GB to 17.75 GB in all the storage devices of the RAID.
$ sudo btrfs filesystem usage /data
Adding Another Storage Device to the Btrfs RAID
To show you how to balance a Btrfs RAID after adding a new storage device, you have to add a new storage device to it.
I have added a new HDD sdf to my computer, which I want to add to the Btrfs RAID mounted on the /data directory. Let's see how to do it.
$ sudo lsblk -e7
Navigate to a different directory (i.e., HOME directory) from the /data directory as follows:
$ cd
To add the storage device sdf to the Btrfs RAID mounted on the /data directory, run the following command:
$ sudo btrfs device add /dev/sdf /data
As you can see, the storage device sdf is added to the Btrfs RAID. The RAID size has increased from 80 GB to 100 GB.
$ sudo btrfs filesystem usage /data
Balancing the Btrfs RAID
As you can see, the newly added storage device (sdf) of the RAID (mounted on the /data directory) has 20 GB unallocated, and the other storage devices (sdb, sdc, sdd, sde, etc.) have 17.75 GB unallocated.
$ sudo btrfs filesystem usage /data
The data1, metadata2, and system-data3 are only available on the existing storage devices of the RAID, not the newly added storage device.
To spread out the data, metadata, and system-data on all the storage devices of the RAID (including the newly added storage device) mounted on the /data directory, run the following command:
$ sudo btrfs balance start --full-balance /data
It may take a while to spread out the data, metadata, and system-data on all the storage devices of the RAID ifit contains a lot of data.
Once the storage devices of the RAID are properly balanced, you should see the following message.
As you can see, after the balance operation is completed, the newly added storage device has an equal amount of unallocated disk space as the other storage devices of the RAID.
After the balance operation, an equal amount of disk space as the other storage devices of the RAID is allocated for the data, metadata, and system-data from the newly added storage device (sdf) of the RAID.
Conclusion
In this article, I have discussed the purpose of the Btrfs balance utility, as well as how to balance a Btrfs RAID or multi-device filesystem after adding new storage devices to the RAID or multi-device filesystem.
