BTRFS

Documentation and configuration for my Btrfs setup.

Overview

This page is my personal Btrfs reference, intended for use on Linux systems where I want snapshot automation, backups, and recovery workflows.

Btrfs snapshots are fast local point-in-time copies, but they are not a substitute for offsite backups. Use snapshots for rollback and local recovery, and use a backup tool such as btrbk to copy data to separate storage.

Why Btrfs

Btrfs is a Linux filesystem with features that are useful for my systems:

• Copy-on-Write (CoW)
• Dynamic inode allocation
• Online defragmentation and resizing
• Built-in RAID
• Built-in compression
  • zstd, lzo, zlib
• Checksums for data and metadata

Snapshot layouts

There are two common layouts I use:

OpenSUSE style

This layout separates system directories into their own subvolumes. It is more work to set up manually, but it gives better rollback control and finer snapshot scope.

/etc/fstab

UUID=8884113b-f807-4ac6-a97a-948fe9eee833 /               btrfs   defaults,subvol=@ 0       0
UUID=8884113b-f807-4ac6-a97a-948fe9eee833 /root           btrfs   defaults,subvol=@root_user 0       0
UUID=8884113b-f807-4ac6-a97a-948fe9eee833 /tmp            btrfs   defaults,subvol=@tmp 0       0
UUID=8884113b-f807-4ac6-a97a-948fe9eee833 /usr/local      btrfs   defaults,subvol=@usr_local 0       0
UUID=8884113b-f807-4ac6-a97a-948fe9eee833 /var            btrfs   defaults,subvol=@var 0       0
UUID=8884113b-f807-4ac6-a97a-948fe9eee833 /opt            btrfs   defaults,subvol=@opt 0       0
UUID=0786fd3e-4e4c-4113-858b-a7f53e676be9 /home           btrfs   defaults,compress=zstd,subvol=@home 0 0

Ubuntu style

This layout keeps root and home separate while using a single Btrfs partition. It is simpler to set up and is compatible with tools such as Timeshift.

/etc/fstab

/dev/mapper/nvme0n1p3_crypt /               btrfs   defaults,subvol=@ 0       0
/dev/mapper/nvme0n1p3_crypt /home           btrfs   defaults,subvol=@home 0       0

Resources

Presentations

BTRFS Lightning Talk - DTG (PDF)

BTRFS Lightning Talk - DTG (YouTube)

Walkthroughs

https://github.com/codeHaiku22/Btrfs-Guide/tree/main

https://christitus.com/btrfs-guide/

https://archive.kernel.org/oldwiki/btrfs.wiki.kernel.org/index.php/SysadminGuide.html

https://archive.kernel.org/oldwiki/btrfs.wiki.kernel.org/index.php/Incremental_Backup.html

Official documentation

https://btrfs.readthedocs.io/en/latest/

Useful tools

Snapshot automation

WARNING

Check Gotchas if you plan on storing snapshots in a location scanned by updatedb.

btrbk

By far the best and most versatile BTRFS backup tool.

BTRFS makes it easy to make snapshots, but snapshots are copies of your data on the same storage, so they aren't good backups; backups should go to another storage place, and btrbk makes that easy. Here's the configuration I use:

/etc/btrbk.conf

archive_preserve       7d 5w 12m 7y
archive_preserve_min   latest
backend_local_user     btrfs-progs-sudo
lockfile               /var/lock/btrbk.lock
snapshot_preserve      6h 2d 2w
snapshot_preserve_min  latest
ssh_identity           /etc/btrbk/ssh/btrbk
ssh_user               root
stream_buffer          256m
target_preserve        24h 7d 4w 12m 1y
target_preserve_min    latest
transaction_log        /var/log/btrbk.log

subvolume    /
	snapshot_dir 	/.snapshots
	target 		/mnt/backup/root/

subvolume 	/home
	snapshot_dir 	/home/.snapshots
	target 		/mnt/backup/home/

subvolume	/root
	snapshot_create	onchange
	snapshot_dir 	/root/.snapshots
	target 		/mnt/backup/root_user/

subvolume	/usr/local
	snapshot_create	onchange
	snapshot_dir 	/usr/local/.snapshots
	target 		/mnt/backup/usr_local/

subvolume	/opt
	snapshot_create	onchange
	snapshot_dir 	/opt/.snapshots
	target 		/mnt/backup/opt/

I run it hourly out of cron:

/etc/cron.hourly/btrbk

#!/bin/sh
exec /usr/local/bin/btrbk -q run

Don't forget to rotate those logs:

/etc/logrotate.d/btrbk

/var/log/btrbk.log {
	rotate 3
	monthly

Timeshift

TIP

Requires Ubuntu Style snapshot layout.

Not really backup, but snapshot automation. Snapshots are great because they are a copy of your data right next to your data, but for that reason they are not good backups -- if the hard drive your data is on dies and that's where your only snapshot copies are, well you're out of luck. A good backup solution should copy those snapshots to a different location, so you can still get them if your main drive fails; Timeshift doesn't have this, btrbk does. The nice thing about it though, is it is built into some distros.

Maintenance

btrfsmaintenance

This tool works well as a set and forget for always mounted drives. See Maitenance Tasks for a list of tasks to run manually on drives that are not always attached.

Configuration option

The special word/mountpoint "auto" will evaluate all mounted btrfs filesystems. This is useful if you have multiple btrfs mount points and you just want them to be found without having to list them all.

Snapshot manipulation

httm

Winner for the coolest name: HTTM stands for "Hot Tub Time Machine".

File system metrics

compsize

Useful for judging how effective compression is working on your subvolume. compsize takes a list of files (given as arguments) on a btrfs filesystem and measures used compression types and effective compression ratio, producing a report.

➜  ~ sudo compsize /home
Processed 5525349 files, 969946 regular extents (9412294 refs), 1791531 inline.
Type       Perc     Disk Usage   Uncompressed Referenced  
TOTAL       65%       49G          75G         719G       
none       100%       30G          30G         340G       
zstd        41%       18G          45G         378G       
prealloc   100%      6.2M         6.2M         297M

Cool Tricks

Take a snapshot before installing/removing/updating a package.

TIP

Details on DPkg::Pre-Install-Pkgs can be found in apt.conf(5).

btrbk

/etc/apt/apt.conf.d/99btrbk

// snapshot the filesystem before installing packages
DPkg::Pre-Install-Pkgs {"/usr/local/bin/btrbk snapshot -qp";};

Timeshift

/etc/apt/apt.conf.d/80-btrfs-snapshot

DPkg::Pre-Install-Pkgs {"/usr/bin/timeshift --scripted --create --comments 'Dpkg::Pre-Install-Pkgs';"};

TIP

To trigger the above when installing .deb files, use apt instead of dpkg

sudo apt install ./package.deb

Gotchas

Tools like plocate make finding files on your computer easy and fast; they do this by scanning your filesystem and building an index with tools like updatedb. These tools will happily traverse BTRFS snapshots and grow their database until they are unusable. To prevent this utilize the PRUNENAMES and PRUNEPATHS configuration options from updatedb.conf

updatedb.conf

PRUNENAMES=".snapshots"
PRUNEPATHS="/mnt/backup"

Maintenance Tasks

Interval	Task	Command
Monthly	Scrub	sudo btrfs scrub start -B /mnt/archive

TIP

Check the status of a scrub with

sudo btrfs scrub status /mnt/archive