Btrfs subvolume layouts and Snapper snapshots

Subvolume layout: a flat structure and separate state#

A flat layout makes separate mounting and recovery easier; nested subvolumes are also valid. The key point is that Btrfs snapshots do not recursively include other subvolumes. Nesting in directory paths does not imply nesting within snapshots.

Snapshots share unchanged data blocks, so a cache is not necessarily copied anew for every snapshot. The main value of a separate subvolume is controlling retention and rollback scope. /var/lib/pacman must remain consistent with the system’s package files and should not be excluded arbitrarily.

Mount options and performance trade-offs#

Start with a simple configuration:

rw,noatime,compress=zstd:3

• compress=zstd:3: a compromise between compression ratio and CPU overhead; check kernel and tool versions for support for negative compression levels.
• ssd, space_cache=v2, and similar options may already be applied automatically by modern kernels. There is no need to add them again merely for “optimization.”
• discard=async: asynchronous TRIM; check kernel defaults, device support, and how this fits with a periodic fstrim policy.
• commit=120: extends the transaction commit interval, increasing the window of state that has not yet been persisted if power is suddenly lost. This is not a cost-free general recommendation; keeping the default is usually simpler.

Snapper configuration#

Installation and first-time initialization

sudo pacman -S snapper snap-pac
sudo snapper -c root create-config /

create-config requires the target subvolume to exist and creates .snapshots. The replacement steps below apply only to a first-time setup with no snapshot data and a separate @snapshots already planned; do not copy these deletion steps into an existing setup.

# 先检查挂载、子卷与内容，确认这里是刚生成且空的 .snapshots
findmnt /.snapshots
sudo btrfs subvolume show /.snapshots
sudo btrfs subvolume list /
# 确认未挂载其他快照卷且没有需要保留的快照后，删除刚生成的子卷
sudo btrfs subvolume delete /.snapshots
sudo mkdir /.snapshots
# /dev/EXAMPLE_BTRFS_PARTITION 为含 @snapshots 的文件系统
sudo mount -o subvol=@snapshots /dev/EXAMPLE_BTRFS_PARTITION /.snapshots
sudo chmod 750 /.snapshots

Then add or verify the corresponding mount in /etc/fstab. If /.snapshots already exists and is in use, migrate it according to the actual layout first. Do not handle it with rm -rf /.snapshots.

Retention policy

For example, in /etc/snapper/configs/root:

TIMELINE_LIMIT_HOURLY="5"
TIMELINE_LIMIT_DAILY="7"
TIMELINE_LIMIT_WEEKLY="0"
NUMBER_LIMIT="10"

Timeline snapshots, number-based snapshots, and cleanup rules are different mechanisms. Check that the corresponding timers are enabled and inspect free space regularly; these values do not impose a guaranteed hard limit on all snapshots.

Monthly checks#

Scrub: detecting checksum errors

sudo btrfs scrub start -B /
sudo btrfs scrub status /

Scrub can verify checksummed data and metadata; automatic repair is possible only when a valid redundant copy exists. Corruption in single-copy data generally still requires recovery from a backup. For automatic scheduled runs, check the timer templates supplied by the distribution and the escaped mount-point name.

Quotas: qgroups and simple quotas

sudo btrfs quota enable --simple /

This example requires squotas support in the kernel and btrfs-progs, and the existing qgroups state must be checked first. squotas account for blocks against the subvolume that first allocated them; this is not the same as shared/exclusive space accounting, and attribution of data that predates enablement is also limited. Do not treat it as a direct replacement for Snapper’s space-aware functionality, and do not assume it guarantees snapshot deletion without any performance impact.

Disaster recovery and booting snapshots#

systemd-boot discovers UKIs by default; it does not automatically list Btrfs snapshots. grub-btrfs can generate GRUB snapshot menu entries, but booting from a snapshot, recovering a writable system, and performing a persistent rollback are separate operations.

A flat @ layout generally requires entering a recovery environment from installation media, restoring the selected read-only snapshot as a new writable @, and then checking fstab and the boot configuration and rebuilding the initramfs. snapper rollback changes the default subvolume, while a mount with an explicit subvol=@ does not necessarily follow that default. Recovery cannot be guaranteed to take just one command.

Before recovery, confirm the target snapshot and backups, and retain the old @ so you can revert. A separately mounted ESP is not included in the root snapshot; the kernel/UKI must also be aligned with the restored system version.

Storage structure#

graph LR
    Disk[物理磁盘] --> Btrfs[Btrfs 文件系统]
    Btrfs --> Root[@ 根子卷]
    Btrfs --> Home[@home 用户数据]
    Btrfs --> Snap[@snapshots 快照目录]
    Root -- 创建快照 --> Snap