thelinuxvault guide

A Practical Guide to Btrfs Backup and Restore

Btrfs (B-tree File System) is a modern, copy-on-write (CoW) filesystem for Linux that offers powerful features like snapshots, subvolumes, checksumming, and built-in RAID support. These features make Btrfs an excellent choice for data integrity and flexibility—but to truly leverage its power, understanding how to back up and restore data is critical. Unlike traditional filesystems, Btrfs simplifies backups through lightweight snapshots and incremental transfers, reducing storage overhead and speeding up recovery. This guide will walk you through **practical strategies, tools, and step-by-step workflows** to back up and restore Btrfs data. Whether you’re a home user or a system administrator, you’ll learn how to protect your data from hardware failures, accidental deletions, and corruption.

Table of Contents

  1. Understanding Btrfs Basics for Backups
    • 1.1 Subvolumes: The Building Blocks
    • 1.2 Snapshots: Lightweight Point-in-Time Copies
  2. Btrfs Backup Strategies
    • 2.1 Local Snapshots: Quick Recovery for Day-to-Day Use
    • 2.2 External Backups: Protecting Against Disk Failure
  3. Essential Tools for Btrfs Backups
    • 3.1 btrfs Subvolume and Snapshot Commands
    • 3.2 btrfs send and btrfs receive: Incremental Transfers
    • 3.3 Rsync: A Complementary Tool
    • 3.4 Third-Party Tools: Automation and Convenience
  4. Step-by-Step: Creating Btrfs Backups
    • 4.1 Local Snapshot Workflow
    • 4.2 Remote/External Backup with btrfs send/receive
  5. Step-by-Step: Restoring Btrfs Data
    • 5.1 Restoring from Local Snapshots
    • 5.2 Restoring from btrfs send/receive Backups
    • 5.3 Restoring Individual Files
  6. Best Practices for Btrfs Backups
  7. Troubleshooting Common Issues
  8. References

1. Understanding Btrfs Basics for Backups

Before diving into backups, let’s clarify two core Btrfs features that enable efficient backup workflows: subvolumes and snapshots.

1.1 Subvolumes: The Building Blocks

A Btrfs subvolume is a logical partition within a Btrfs filesystem. Think of it as a “virtual filesystem” with its own directory tree, but sharing the same underlying storage pool as the parent filesystem. Subvolumes:

  • Are independent of each other (e.g., deleting a subvolume doesn’t affect others).
  • Can be mounted separately (e.g., /, /home, or /var as subvolumes).
  • Are the target of Btrfs snapshots (you can’t snapshot a regular directory—only a subvolume).

To list subvolumes on a Btrfs filesystem (e.g., mounted at /mnt/btrfs):

btrfs subvolume list /mnt/btrfs

1.2 Snapshots: Lightweight Point-in-Time Copies

A Btrfs snapshot is a read-only or read-write copy of a subvolume at a specific moment. Thanks to CoW, snapshots are lightweight—they initially consume no additional space, only growing when data in the original subvolume or snapshot is modified.

  • Read-only snapshots: Ideal for backups (prevents accidental changes). Created with -r.
  • Read-write snapshots: Useful for testing changes (e.g., updating software) before applying them to the original subvolume.

Snapshots are stored as subvolumes themselves, making them easy to manage and mount.

2. Btrfs Backup Strategies

Btrfs offers multiple backup approaches, each suited to different scenarios. Combine them for robust data protection.

2.1 Local Snapshots: Quick Recovery for Day-to-Day Use

Use case: Recovering from accidental deletions, corrupted files, or failed updates on the same disk.
Pros: Fast to create/restore, minimal overhead, no external storage needed.
Cons: Useless if the disk fails (e.g., hardware failure, ransomware).

Example workflow: Daily read-only snapshots of /home and /root.

2.2 External Backups: Protecting Against Disk Failure

Use case: Safeguarding data from disk failures, theft, or natural disasters.
Pros: Protects against catastrophic loss, supports offsite storage.
Cons: Requires external storage (USB drive, network share, cloud).

Btrfs simplifies external backups with btrfs send and btrfs receive, which transfer snapshots incrementally (only changed data is sent).

3. Essential Tools for Btrfs Backups

3.1 btrfs Subvolume and Snapshot Commands

The btrfs utility is your primary tool for managing subvolumes and snapshots:

  • Create a read-only snapshot:

    btrfs subvolume snapshot -r /mnt/btrfs/original_subvol /mnt/btrfs/snapshots/original_subvol_20240520

    Here, -r makes it read-only, original_subvol is the source subvolume, and original_subvol_20240520 is the snapshot name (include a timestamp for clarity).

  • Delete a snapshot:

    btrfs subvolume delete /mnt/btrfs/snapshots/original_subvol_20240520

3.2 btrfs send and btrfs receive: Incremental Transfers

btrfs send generates a binary stream of a snapshot’s data, which can be piped to btrfs receive on a remote or external Btrfs filesystem. This is ideal for incremental backups:

  • Initial full backup: Send the first snapshot.
  • Incremental backup: Send only changes since the last snapshot (using -p for “parent” snapshot).

Example: Send a snapshot to a remote server via SSH:

btrfs send /mnt/btrfs/snapshots/snap1 | ssh user@remote "btrfs receive /mnt/backup/btrfs_snapshots"

3.3 Rsync: A Complementary Tool

While btrfs send/receive are Btrfs-optimized, rsync works for non-Btrfs external storage (e.g., ext4 USB drives). Use rsync -aAX to preserve permissions, ACLs, and extended attributes:

rsync -aAX --delete /mnt/btrfs/home/ /mnt/external_drive/home_backup/

3.4 Third-Party Tools: Automation and Convenience

For automated backups, use tools like:

  • Snapper: Configures automatic snapshots (e.g., pre/post-update snapshots for /). Integrates with package managers (DNF, apt).
  • Timeshift: GUI/CLI tool for system snapshots (similar to Windows System Restore). Supports Btrfs and ext4.
  • Btrbk: Lightweight script for automated send/receive backups (supports SSH, incremental backups, and retention policies).

4. Step-by-Step: Creating Btrfs Backups

4.1 Local Snapshot Workflow

Let’s create daily read-only snapshots of a /home subvolume (mounted at /mnt/btrfs/home).

Step 1: Organize Snapshots

Store snapshots in a dedicated directory (e.g., /mnt/btrfs/snapshots/home):

mkdir -p /mnt/btrfs/snapshots/home

Step 2: Create a Read-Only Snapshot

# Replace "20240520" with a timestamp (e.g., $(date +%Y%m%d_%H%M))  
SNAP_NAME="home_snap_$(date +%Y%m%d_%H%M)"  
btrfs subvolume snapshot -r /mnt/btrfs/home /mnt/btrfs/snapshots/home/$SNAP_NAME

Step 3: Automate with a Cron Job

To create snapshots daily at 3 AM, add this to crontab -e:

0 3 * * * /bin/bash -c 'SNAP_NAME="home_snap_$(date +%Y%m%d_%H%M)"; btrfs subvolume snapshot -r /mnt/btrfs/home /mnt/btrfs/snapshots/home/$SNAP_NAME'

4.2 Remote Backup with btrfs send/receive

Let’s back up snapshots to a remote server (e.g., backup-server) over SSH.

Prerequisites:

  • The remote server has a Btrfs filesystem mounted at /mnt/backup (create it with mkfs.btrfs /dev/sdX if needed).
  • SSH access to backup-server (passwordless login recommended via SSH keys).

Step 1: Send the Initial Snapshot

First, send a full snapshot to the remote server:

# On the local machine:  
SNAP_NAME="home_snap_20240520_0300"  
btrfs send /mnt/btrfs/snapshots/home/$SNAP_NAME | ssh user@backup-server "btrfs receive /mnt/backup/btrfs_snapshots"

Step 2: Send Incremental Updates

After creating a new snapshot (home_snap_20240521_0300), send only the changes since the previous snapshot:

NEW_SNAP="home_snap_20240521_0300"  
OLD_SNAP="home_snap_20240520_0300"  
btrfs send -p /mnt/btrfs/snapshots/home/$OLD_SNAP /mnt/btrfs/snapshots/home/$NEW_SNAP | ssh user@backup-server "btrfs receive /mnt/backup/btrfs_snapshots"

The -p flag specifies the parent snapshot, enabling incremental transfer.

5. Step-by-Step: Restoring Btrfs Data

5.1 Restoring from Local Snapshots

Scenario: Accidentally deleted a file in /home/user/docs.

Option 1: Mount the snapshot and copy the file
Snapshots are mountable, so you can browse and recover individual files:

# Mount the snapshot (e.g., home_snap_20240520_0300)  
mkdir /mnt/snap  
mount -o subvol=snapshots/home/home_snap_20240520_0300 /dev/sda2 /mnt/snap  # Replace /dev/sda2 with your Btrfs device  

# Copy the lost file back  
cp /mnt/snap/user/docs/lost_file.txt /home/user/docs/  

# Unmount the snapshot  
umount /mnt/snap

Option 2: Replace the entire subvolume with the snapshot
Use this if the original subvolume is severely corrupted (e.g., after a failed OS update):

# 1. Rename the corrupted subvolume (as a backup)  
mv /mnt/btrfs/home /mnt/btrfs/home_corrupted  

# 2. Create a read-write copy of the snapshot (since we can’t modify read-only snapshots directly)  
btrfs subvolume snapshot /mnt/btrfs/snapshots/home/home_snap_20240520_0300 /mnt/btrfs/home  

# 3. Verify the restore  
ls /mnt/btrfs/home

5.2 Restoring from btrfs send/receive Backups

Scenario: Disk failure—restore /home from a remote backup to a new Btrfs filesystem.

Step 1: Prepare the new Btrfs filesystem
Create a new Btrfs filesystem on the replacement disk (e.g., /dev/sdb1) and mount it:

mkfs.btrfs /dev/sdb1  
mount /dev/sdb1 /mnt/new_btrfs

Step 2: Receive the snapshot from the remote server

ssh user@backup-server "btrfs send /mnt/backup/btrfs_snapshots/home_snap_20240520_0300" | btrfs receive /mnt/new_btrfs

Step 3: Promote the snapshot to a usable subvolume
The received snapshot is a read-only subvolume. Convert it to a read-write subvolume:

mv /mnt/new_btrfs/home_snap_20240520_0300 /mnt/new_btrfs/home

5.3 Restoring Individual Files

As with local snapshots, mount the received snapshot and copy files:

mount -o subvol=home_snap_20240520_0300 /dev/sdb1 /mnt/snap  
cp /mnt/snap/user/important_file.txt /mnt/new_btrfs/home/user/  
umount /mnt/snap

6. Best Practices for Btrfs Backups

  1. Prioritize read-only snapshots: Prevents accidental modification of backups.
  2. Automate snapshots: Use cron, Snapper, or Btrbk to avoid manual errors.
  3. Test restores regularly: A backup is useless if you can’t restore from it!
  4. Limit snapshot retention: Delete old snapshots to free space (e.g., keep 7 daily, 4 weekly, 3 monthly snapshots).
  5. Monitor disk space: Snapshots grow as data changes—use btrfs filesystem df /mnt/btrfs to check free space.
  6. Encrypt external backups: Use cryptsetup (LUKS) on external drives or SSH/HTTPS for network transfers.
  7. Follow the 3-2-1 rule: 3 copies of data, 2 on different media, 1 offsite.

7. Troubleshooting Common Issues

”btrfs send: not a snapshot”

Cause: You’re trying to send a regular subvolume, not a snapshot.
Fix: Ensure the source is a snapshot (created with btrfs subvolume snapshot -r).

”No space left on device”

Cause: Snapshots or the original subvolume have consumed all disk space.
Fix: Delete old snapshots with btrfs subvolume delete, or run btrfs balance start /mnt/btrfs to reclaim space (if using RAID).

Corrupted snapshot

Cause: Disk errors or unexpected power loss during snapshot creation.
Fix: Check the filesystem with btrfs check --readonly /dev/sdX (unmount first). For severe corruption, restore from an external backup.

8. References

By combining local snapshots for quick recovery and btrfs send/receive for external backups, you can ensure your data is protected against both minor mishaps and catastrophic failures. Start small with daily snapshots, then expand to remote backups for full peace of mind!