Retired Techie

Introduction

Today, I want to examine the btrfs filesystem on Manjaro Linux. Interestingly, it appears as the default option in the installer for Manjaro 26.1 (Bian-May). I will explore how btrfs is setup in this version.

For those unfamiliar with Btrfs, it is a modern Linux filesystem that supports features such as subvolumes, snapshots, checksums, compression, RAID, and multi-device configurations. In this article, I’ll cover three main topics:

• A high-level overview of Btrfs
• Btrfs specifically on Manjaro
• How to add disks to expand an existing Btrfs filesystem

Although Btrfs supports RAID and snapshots, neither feature is a replacement for regular backups. If you already make backups, keep doing so. If you don’t, now is a good time to start.

High Level Overview BTRFS

Btrfs, short for B-tree File System, is a modern copy-on-write filesystem for Linux. It was developed by Chris Mason in 2007 and is supported directly by the Linux kernel. It may also be referred to as Better FS, Butter FS, or B-tree FS. Btrfs provides features such as snapshots, subvolumes, checksums, compression, data scrubbing, and support for managing multiple storage devices.

Copy-on-write, or COW, is one of Btrfs’s fundamental features. When data is modified, Btrfs writes the new version to a different location instead of immediately overwriting the original. It then updates the filesystem metadata to reference the new version. This helps maintain filesystem consistency after crashes or power failures and enables efficient snapshots.

Older filesystems, such as EXT4 and FAT, primarily provided basic file storage and organization with limited management features. Btrfs belongs to a newer generation of filesystems with more advanced capabilities. ZFS is another example. LVM, although not technically a filesystem, is a related storage-management technology that provides logical volumes, resizing, and snapshots.

For this discussion, think of Btrfs as a filesystem operating across one or more block devices, such as NVMe drives, SSDs, or mechanical disks. These devices provide addressable blocks for storing the operating system, applications, and user data.

Btrfs can manage multiple devices as a single filesystem. It presents a unified logical storage space while mapping logical addresses to physical locations on the participating devices.

For example, the Btrfs single profile can be used for both data and metadata. This combines the devices’ capacity and resembles a JBOD-style arrangement (Just a Bunch Of Disks), but it provides no protection against device failure. Other Btrfs profiles can provide mirroring or striping, depending on how the filesystem is created.

Btrfs stores data and metadata in allocated chunks. File contents are represented by extents, while metadata is organized into multiple B-trees. These trees track files, directories, extents, devices, chunks, subvolumes, and checksums.

Btrfs calculates checksums for data and metadata. When data is read, it can compare the stored checksum with a newly calculated checksum to detect corruption.

At the filesystem interface, users work with files and directories. Btrfs also provides subvolumes and snapshots. A subvolume is an independent filesystem tree within a larger Btrfs filesystem. A snapshot is a copy-on-write subvolume based on an existing one. Initially, it shares blocks with its source and consumes additional space only as changes occur. This makes snapshots efficient while preserving an earlier version of the filesystem’s contents.

Installing Manjaro with BTRFS

At the time of writing, the current Manjaro release is version 26.1.0, codenamed “Bian-May.” However, Manjaro uses a rolling-release model, so the installer and version may change through updates and future releases.

There is one important note for VM managers: the default UEFI boot options, if they include “secure boot”, do not work with Manjaro in my testing. Only using UEFI without Secure Boot worked for me.

During installation, the storage section includes Btrfs as an available filesystem. In my test installation, Btrfs appeared as the default selection. Choosing Btrfs is sufficient to install the filesystem and begin using it.

The Manjaro installer appears to be designed primarily for systems with a single storage drive. Based on my limited testing of this version, it does not provide an option to configure a Btrfs filesystem across multiple drives, either automatically or manually.

I also have not found a easy way to modify Manjaro’s default subvolume layout during installation. The default subvolumes include root, home, logs, and cache.

So far, I have found it easiest to modify the Btrfs layout after completing the installation. I have researched several other available methods, but they are more complex to implement and generally less user-friendly.

Exploring BTRFS on Manjaro

Let’s log in to Manjaro and open a terminal. Currently, there is no single, universally adopted graphical tool for managing Btrfs. Some distributions provide graphical utilities, but these tools are not available everywhere and may work differently from one distribution to another. As a result, the command line remains the most widely applicable way to manage Btrfs.

Because this is a new installation, the first step is to examine the filesystem. There are several ways to do this, so we’ll use a few different tools. You can try them and use whichever ones you find most comfortable.

The lsblk command displays a list of the system’s block devices:

    lsblk -f

In this example, the vda1 partition contains a Btrfs filesystem that is accessed through four mounted subvolumes: /, /home, /var/log, and /var/cache.

The -f option displays additional filesystem information, including the filesystem type, label, and universally unique identifier (UUID).

The df command displays information about used and available disk space. With the -h option, sizes are shown in a human-readable format:

    df -h

The -h option displays sizes in a human-readable format, using powers of 1024. Depending on the system, the output may use units such as KiB, MiB, and GiB.

The btrfs command is a toolbox-style utility with several subcommands, incuding:

• btrfs filesystem

• btrfs subvolume

• btrfs device

Each subcommand has its own help information and manual page. These subcommands are also listed in the main Btrfs manual page. For a quick reference, use the built-in help menu:

    btrfs --help

Before examining the Btrfs commands, it helps to understand the basic layout of a Btrfs filesystem.

A single Btrfs filesystem can contain several separate sections called subvolumes. Each subvolume can be mounted at a different location in the directory structure. In this example, one Btrfs filesystem is accessed through several mount points. The subvolumes share the same underlying storage, but each appears at a different location and can serve a different purpose.

When Btrfs is mounted, it normally presents one selected subvolume. If no particular subvolume is specified, Btrfs uses its default subvolume. It is also possible to mount the top-level Btrfs structure directly, which makes it easier to view and manage the filesystem’s subvolumes.

Many Btrfs commands use a mount point rather than the storage device itself. Depending on the command, any suitable mount point may work. Tutorials often use /mnt as a temporary location for accessing the top-level Btrfs structure.

Let’s use the btrfs command to examine the subvolumes. Because a Btrfs subvolume is mounted at /, we can use / as the path. Administrative privileges may be required to view all of the available information, so we will use sudo:

    sudo btrfs subvolume list /

This command lists the Btrfs subvolumes associated with the filesystem containing /. Note the @ symbols in names such as @, @home, and @log. On many Linux distributions, the @ subvolume is used for the root filesystem, while @log may be mounted at /var/log. These names are internal Btrfs subvolume names. They are conventions rather than requirements, and they do not necessarily correspond directly to the paths where the subvolumes are mounted.

Another way to examine mounted filesystems is to use the findmnt command with the -t option to specify the filesystem type:

    findmnt -t btrfs

This command displays the mounted Btrfs filesystems, their mount points, and their mount options. It may also show the corresponding Btrfs subvolume names.

You can also examine the /etc/fstab file with the cat command:

    cat /etc/fstab

This file shows how filesystems are mounted during system startup, including the mount points and their relationship to Btrfs subvolumes.

The Btrfs tools can provide additional information about the filesystem and how its storage is being used:

    sudo btrfs filesystem show 
    sudo btrfs filesystem usage /

The first command displays information about the Btrfs filesystem and its devices. The second provides a more detailed breakdown of allocated and used space.

This is probably more information than the average user wants to dig through. However, if you encounter problems and ask for help, you may be asked to provide the output from some of these commands. For that reason, it is helpful to be familiar with them.

Adding a New Storage Device

Once the new device is installed, the first step is to identify it:

    lsblk

Be certain that you have identified the correct unused device. Selecting the wrong device during the following steps could destroy existing data.

In this example, the new device is /dev/vdb. You can either use the entire device or create a partition on it. Using a partition leaves the remaining space available for other partitions or future uses. Using the entire device dedicates all of its space to Btrfs and may make later repartitioning less convenient.

To create a partition on the device, use cfdisk:

    sudo cfdisk /dev/vdb

Create a partition such as /dev/vdb1. A new partition does not need to be formatted separately before it is added to an existing Btrfs filesystem. In fact, formatting it separately is unnecessary and may interfere with the device-add operation.

Add the new partition to the existing Btrfs filesystem:

    sudo btrfs device add /dev/vdb1 /

The final argument, /, identifies the target Btrfs filesystem through a mounted path. It does not refer to the new device.

Many tutorials recommend temporarily mounting the top-level Btrfs structure at a directory such as /mnt and using that path instead. That approach can be useful when the filesystem’s layout is unknown. However, for this operation, any suitable mounted path belonging to the target Btrfs filesystem can generally be used. In this example, / is one of the mounted subvolumes belonging to that filesystem.

Adding a device increases the storage available to the Btrfs filesystem, but it does not automatically redistribute existing data across the devices.

To verify that the device is now part of the Btrfs filesystem, run:

    sudo btrfs filesystem show /

    lsblk -f

You can also examine the available space:

    df -h

    sudo btrfs filesystem usage /

The df -h command reports the space visible through mounted filesystems. The btrfs filesystem usage command provides more detailed Btrfs-specific information, including data chunks, metadata chunks, device allocation, profiles, and unallocated space.

A balance operation can relocate existing data and metadata block groups. This may help distribute existing allocations across the devices:

    sudo btrfs balance start -dusage=50 -musage=50 /

The options mean:

• -dusage=50 processes data block groups that are 50 percent utilized or less.
• -musage=50 processes metadata block groups that are 50 percent utilized or less.

A balance is not always required immediately after adding a device. Btrfs can generally use the new device for future allocations without first balancing the filesystem. A filtered balance may be useful when you want to redistribute existing allocations, but it does not guarantee that all data will be evenly distributed across the devices.

A balance operation can take considerable time and generate substantial disk activity. You can monitor its progress with:

    sudo btrfs balance status /

For a complete balance, omit the usage filters:

    sudo btrfs balance start /

A full balance is usually more expensive than necessary, so a filtered balance is generally the better first step.

Adding a device does not automatically create redundancy. Existing data and metadata may continue to use the single profile, which does not provide a mirrored copy.

If the goal is to create Btrfs RAID1-style redundancy, the data and metadata profiles must be converted explicitly:

    sudo btrfs balance start -dconvert=raid1 -mconvert=raid1 /

Do not run this command unless the filesystem has enough suitable devices and redundancy is actually intended. The conversion may require substantial free space and can take a long time. Also, converting the profiles does not replace a backup; it protects against certain device failures but is not a substitute for independent backups.

Conclusion

In this post, we examined the Btrfs file system as installed on Manjaro. We explored several commands, both Btrfs-specific and standard system commands, for examining the file system. We identified the file system and its subvolumes, along with their mount points. Finally, we added a new device to the file system.

At this point, you should have a basic working knowledge of Btrfs on Manjaro, as well as an understanding of how to use command-line tools to examine and modify the file system.

Btrfs is a relatively new file system that includes built-in management features, and a number of Linux distributions now use it by default. Although Btrfs can improve file-system management, it is still under development and has several known issues. Unless you rely on one of its niche features or use cases, Btrfs should be stable and suitable for most users.