Skip to content

Latest commit

 

History

History
146 lines (121 loc) · 7.68 KB

btrfs.md

File metadata and controls

146 lines (121 loc) · 7.68 KB

Btrfs

Btrfs is a copy-on-write Linux filesystem with built-in subvolumes, snapshots, checksums, compression, multi-device RAID profiles and send/receive replication. Use it for snapshotting root and data volumes, or as a single-host alternative to ZFS that ships in the mainline kernel.

Documentation: Btrfs documentation · btrfs(8) manual pages Project: btrfs-progs

Verification: subcommands and options were checked against the btrfs-progs 6.6.3 man pages in Ubuntu 24.04. No filesystem was created or mounted. Commands marked destructive delete or overwrite data. RAID5 and RAID6 profiles are documented upstream as having known problems: avoid them for data you care about.

Create and Mount

COMMAND DESCRIPTION
sudo mkfs.btrfs -L <LABEL> /dev/<DEVICE> Formats the device. Single-device filesystem
sudo mkfs.btrfs -L <LABEL> -d raid1 -m raid1 /dev/<DEV1> /dev/<DEV2> Formats both devices. Mirror data and metadata
sudo mkfs.btrfs -d single -m raid1 /dev/<DEV1> /dev/<DEV2> Data spread without redundancy, metadata mirrored
sudo mount /dev/<DEVICE> /mnt/data Mount (any device of a multi-device filesystem works)
sudo mount -o compress=zstd,noatime /dev/<DEVICE> /mnt/data Compression and no access-time updates
sudo mount -o subvol=<NAME> /dev/<DEVICE> /mnt/data Mount a subvolume by name
sudo btrfs filesystem label /mnt/data <NEWLABEL> Change the label

/etc/fstab entry:

UUID=FILESYSTEM_UUID /mnt/data btrfs defaults,noatime,compress=zstd,subvol=@data 0 0

Find the UUID with lsblk -f (see Storage and Filesystems).

Subvolumes

A subvolume looks like a directory but can be snapshotted, mounted and sent separately.

COMMAND DESCRIPTION
sudo btrfs subvolume create /mnt/data/<NAME> New subvolume
sudo btrfs subvolume list /mnt/data List subvolumes with IDs
sudo btrfs subvolume show /mnt/data/<NAME> Details, including UUID and snapshots
sudo btrfs subvolume delete /mnt/data/<NAME> Deletes the subvolume and its data
sudo btrfs subvolume get-default /mnt/data Default subvolume mounted when none is named
sudo btrfs subvolume set-default <ID> /mnt/data Change the default subvolume
sudo btrfs subvolume sync /mnt/data Wait for deleted subvolumes to be cleaned up

A common layout uses top-level subvolumes such as @ (root), @home and @snapshots, each mounted with subvol=.

Snapshots

COMMAND DESCRIPTION
sudo btrfs subvolume snapshot /mnt/data/<NAME> /mnt/data/.snapshots/<NAME>-$(date +%F) Writable snapshot
sudo btrfs subvolume snapshot -r /mnt/data/<NAME> /mnt/data/.snapshots/<NAME>-$(date +%F) Read-only snapshot (needed for send)
sudo btrfs subvolume delete /mnt/data/.snapshots/<SNAPSHOT> Deletes a snapshot
cp -a --reflink=always <FILE> <COPY> Instant copy sharing blocks (same filesystem only)

To roll back, move or mv the broken subvolume away and snapshot the good one into its place, or use set-default and remount. Tools such as Snapper or btrbk automate retention (not covered here).

Send and Receive

Replicate read-only snapshots to another Btrfs filesystem or file.

# full send
sudo btrfs send /mnt/data/.snapshots/SNAP1 | sudo btrfs receive /mnt/backup

# incremental: send only the difference from a snapshot both sides already have
sudo btrfs send -p /mnt/data/.snapshots/SNAP1 /mnt/data/.snapshots/SNAP2 | sudo btrfs receive /mnt/backup

# to a remote host
sudo btrfs send /mnt/data/.snapshots/SNAP1 | ssh <USER>@<HOST> 'sudo btrfs receive /mnt/backup'
COMMAND DESCRIPTION
btrfs send -p <PARENT> <SNAPSHOT> Incremental stream against a parent present on both sides
btrfs send -f <FILE> <SNAPSHOT> Write the stream to a file
btrfs receive -f <FILE> <DIR> Read a stream from a file

Scrub, Balance and Space

COMMAND DESCRIPTION
sudo btrfs scrub start /mnt/data Verify checksums and repair from redundancy (runs in the background)
sudo btrfs scrub start -B /mnt/data Run in the foreground
sudo btrfs scrub status /mnt/data Progress and error counts
sudo btrfs scrub cancel /mnt/data / resume /mnt/data Stop and continue
sudo btrfs filesystem usage /mnt/data Real allocation: data, metadata, unallocated space
sudo btrfs filesystem df /mnt/data Per-type usage
sudo btrfs filesystem show Filesystems and member devices
sudo btrfs balance start -dusage=50 /mnt/data Compact data chunks that are under 50% full
sudo btrfs balance start -musage=50 /mnt/data Same for metadata chunks
sudo btrfs balance status /mnt/data Progress
sudo btrfs balance cancel /mnt/data Stop a balance
sudo btrfs filesystem defragment -r /mnt/data/<DIR> Defragment (breaks block sharing with snapshots; use sparingly)

df is unreliable on Btrfs: use btrfs filesystem usage. A full filesystem with free data space usually means no unallocated space for new metadata chunks: a filtered balance frees it.

Devices and RAID

COMMAND DESCRIPTION
sudo btrfs device add /dev/<DEVICE> /mnt/data Add a device
sudo btrfs device remove /dev/<DEVICE> /mnt/data Remove a device (data is migrated off first)
sudo btrfs device stats /mnt/data Per-device error counters
sudo btrfs device scan Register devices after boot or hotplug
sudo btrfs replace start /dev/<OLD> /dev/<NEW> /mnt/data Replace a device in place
sudo btrfs replace status /mnt/data Progress
sudo btrfs filesystem resize max /mnt/data Grow to fill the device after enlarging it
sudo btrfs filesystem resize -10G /mnt/data Shrink by 10 GiB
sudo btrfs balance start -dconvert=raid1 -mconvert=raid1 /mnt/data Convert profiles (for example single to RAID1)

Quotas

COMMAND DESCRIPTION
sudo btrfs quota enable /mnt/data Enable quota groups (adds overhead with many snapshots)
sudo btrfs qgroup show /mnt/data Usage per quota group
sudo btrfs qgroup limit 100G /mnt/data/<NAME> Limit a subvolume
sudo btrfs qgroup limit none /mnt/data/<NAME> Remove the limit

Copy-on-Write and Databases

COMMAND DESCRIPTION
chattr +C /mnt/data/<EMPTY_DIR> Disable copy-on-write for new files in an empty directory (databases, VM images); also disables checksums and compression for them
lsattr -d /mnt/data/<DIR> Check the C attribute

Setting +C on a file that already has data does not change existing extents.

Repair and Recovery

COMMAND DESCRIPTION
sudo btrfs check /dev/<DEVICE> Read-only check of an unmounted filesystem
sudo btrfs check --repair /dev/<DEVICE> Last resort, can make things worse: back up first and read the upstream warning
sudo btrfs restore /dev/<DEVICE> /mnt/recovery Copy files off an unmountable filesystem without writing to it
sudo dmesg | grep -i btrfs Kernel messages

Troubleshooting

SYMPTOM FIX
No space left on device but df shows free space btrfs filesystem usage; run balance start -dusage=20 to free chunks
Checksum errors in dmesg btrfs scrub start, btrfs device stats; check the disk with smartctl
Slow after many snapshots Reduce snapshot count; avoid quotas if unneeded
Cannot mount degraded RAID1 mount -o degraded, then btrfs replace the missing device
Snapshots missing space after delete Deletion is asynchronous: btrfs subvolume sync

See Also