Btrfs Primer

Btrfs (B-Tree File System) is a modern "copy-on-write" (CoW) filesystem for Linux. It integrates volume management and RAID features directly into the filesystem level.

Key Features

• Multi-disk volumes: Combine multiple physical drives into a single logical pool.
• RAID Support: Native support for RAID0, RAID1 (mirroring), RAID10, and RAID5/6 (though RAID5/6 is still considered experimental/unstable for metadata).
• On-the-fly compression: Reduces disk footprint and can improve I/O performance (zstd, lzo, zlib).
• Checksumming: Every block is checksummed to prevent bit rot. In a RAID1 setup, Btrfs uses these checksums to automatically detect and repair corrupted data.
• Online Management: Expand volumes, shrink volumes, or swap hardware without unmounting.
• Subvolumes & Snapshots: Create near-instant, atomic "checkpoints" of your data.

Mount Options

Commonly used flags in /etc/fstab or with the mount command:

• -o compress Enables transparent compression (e.g., compress=zstd).
• -o degraded Allows the filesystem to mount even if one or more devices in a RAID array are missing or failed.

Creating a Filesystem or RAID

• mkfs.btrfs [-L LABEL] [-m raid1 -d raid1] DEVICE1 [DEVICE2 ...] Creates a Btrfs filesystem. You can add multiple disks immediately or start with one and expand later.
  • -m raid1: Mirrors the metadata.
  • -d raid1: Mirrors the data.
  • Note: raid1c3 and raid1c4 are available in modern kernels for 3nd or 4th copies of data.

Converting Single Disk to RAID1

If you start with one disk and want to add a second disk to create a RAID1 later:

1. Add the new device: sudo btrfs device add /dev/sdX /mnt/point
2. Convert the data layout: sudo btrfs balance start -dconvert=raid1 -mconvert=raid1 /mnt/point

Essential Btrfs Commands

Filesystem Management

• btrfs filesystem show /mnt/point Shows the UUID and all physical devices associated with the volume.
• btrfs filesystem label /mnt/point [NEWLABEL] Changes the label of the filesystem.
• btrfs filesystem resize [+/-]SIZE|max /mnt/point Resizes a mounted filesystem. Using max expands it to the full size of the partition.
• btrfs filesystem usage /mnt/point The most accurate way to see used/free space for Data and Metadata across all devices.

Device Management

• btrfs device stats /mnt/point Displays I/O errors (read, write, corruption). This is the first place to look if you suspect a failing disk.
• btrfs device add DEVICE /mnt/point Adds a new physical device to the pool.
• btrfs device remove DEVICE|DEVID /mnt/point Removes a disk. Btrfs will automatically move data from the removed disk to the remaining healthy disks before finalizing the removal.
• btrfs device usage /mnt/point Shows individual disk usage per physical device.

Subvolumes and Snapshots

Subvolumes behave like directories but can be managed independently. Note: A snapshot is not a backup because it exists on the same physical disks; it is a point-in-time recovery tool.

• btrfs subvolume create /mnt/point/NAME Creates a new subvolume.
• btrfs subvolume list /mnt/point Lists all subvolumes within the filesystem.
• btrfs subvolume snapshot [-r] SOURCE DEST Creates a snapshot.
  • Use -r for a read-only snapshot (highly recommended for security and for use with btrfs send/receive).