Using the btrfsck file-checing command on Linux

The btrfsck command is a filesystem-check command like fsck, but it works with the btrfs file system.

First a little bit about btrfs. As the name implies, btrfs uses a B-tree data structure that is self-balancing and maintains sorted data, facilitating searches, sequential access, insertions, and deletions. It is also often referred to as the “better file system”. Oracle developed it and first used it about 15 years ago. By November 2013, it was declared adequately stable and began to be used by other distributions as well, and now its use is quite common.

Benefits of btrfs

The benefits of btrfs are impressive, although it’s still a work in progress and some concerns have kept it from playing a more dominant role on Linux systems. It keeps 2 copies of metadata on a volume, allowing for data recovery if and when the hard drive is damaged or suffers from bad sectors. It uses checksums and verifies them with each read. In addition, compared to ext4 volumes, btrfs does not require double the storage space to accommodate file versioning and history data.

When you list file systems as shown below for a Fedora system, you may see that some of them are btrfs. The -T option provides the file system type while the -h option adjusts the sizes to be displayed in a human-friendly (size appropriate units) fashion.

$ df -Th
Filesystem     Type      Size  Used Avail Use% Mounted on
devtmpfs       devtmpfs  2.9G     0  2.9G   0% /dev
tmpfs          tmpfs     2.9G     0  2.9G   0% /dev/shm
tmpfs          tmpfs     1.2G  3.1M  1.2G   1% /run
/dev/sdb4      btrfs      31G  5.5G   25G  19% /
tmpfs          tmpfs     2.9G  132K  2.9G   1% /tmp
/dev/sdb3      ext4      974M  237M  670M  27% /boot
tmpfs          tmpfs     593M  924K  592M   1% /run/user/1000
/dev/sdc1      ext4      974M  174M  733M  20% /extra
/dev/sdc2      btrfs     2.0T  2.9G  2.0T   1% /data/xfer

To use btrfsck, the targeted file system should first be unmounted from the system.

$ sudo umount /dev/sdc2

The unmount can then be confirmed.

$ df -Th
Filesystem     Type      Size  Used Avail Use% Mounted on
devtmpfs       devtmpfs  2.9G     0  2.9G   0% /dev
tmpfs          tmpfs     2.9G     0  2.9G   0% /dev/shm
tmpfs          tmpfs     1.2G  3.1M  1.2G   1% /run
/dev/sdb4      btrfs      31G  5.5G   25G  19% /
tmpfs          tmpfs     2.9G  132K  2.9G   1% /tmp
/dev/sdb3      ext4      974M  237M  670M  27% /boot
tmpfs          tmpfs     593M  924K  592M   1% /run/user/1000
/dev/sdc1      ext4      974M  174M  733M  20% /extra

At this point, it is OK to run the file system check. The file system shown in this example is quite large, but only a small portion of it is in use. The output below shows the phases that the check runs through.

$ sudo btrfsck /dev/sdc2
Opening filesystem to check...
Checking filesystem on /dev/sdc2
UUID: 51749cdf-6fe9-4a1a-8379-18c913660f7b
[1/7] checking root items
[2/7] checking extents
[3/7] checking free space cache
[4/7] checking fs roots
[5/7] checking only csums items (without verifying data)
[6/7] checking root refs
[7/7] checking quota groups skipped (not enabled on this FS)
found 2909151232 bytes used, no error found           <== no errors
total csum bytes: 2672248
total tree bytes: 171720704
total fs tree bytes: 161021952
total extent tree bytes: 7274496
btree space waste bytes: 26580815
file data blocks allocated: 2737430528
 referenced 5166080000

As you can see, no errors were found.

Checking mounted btrfs file systems

Unmounting file systems before running btrfsck is the recommended approach. When you cannot—such as when the file system is your root (/) file system—it is possible to force a check using the –force option as shown below.

# btrfsck --check --force /dev/sdb4
Opening filesystem to check...
WARNING: filesystem mounted, continuing because of --force
Checking filesystem on /dev/sdb4
UUID: 674d8f43-81a6-4713-81d5-9d7506cd6d69
[1/7] checking root items
[2/7] checking extents
[3/7] checking free space cache
[4/7] checking fs roots
[5/7] checking csums against data
[6/7] checking root refs
[7/7] checking quota groups skipped (not enabled on this FS)
found 5864960000 bytes used, no error found
total csum bytes: 5478800
total tree bytes: 225935360
total fs tree bytes: 206061568
total extent tree bytes: 12435456
btree space waste bytes: 50394664
file data blocks allocated: 16850681856
 referenced 8673013760

Other file system types

Other file system types used on this system include:

• The devtmpfs file system is one with includes automated device nodes populated by the kernel.
• The tmpfs file system is one which keeps all of its files in virtual memory.
• The ext4 file system is a journaling file system developed as the successor to ext3. A journaling file system is one that keeps track of changes not yet committed to the file system by recording the goal of such changes. Ext4 also provides large file system support, improved resistance to fragmentation, higher performance and improved timestamps.