scripts-fabq/notes/btrfs.md

BTRFS

Table of Contents

• BTRFS
  • Table of Contents
  • Placeholders
  • BTRFS Command Shorthands
  • Information on Filesystem
  • Drive Manipulation
    • Replace Drives
  • Filesystem Manipulation
    • Upgrading Btrfs Block Group Cache to V2
    • Defrag
  • Balances
  • Scrub
  • Snapshots
    • Create Snapshots
    • Delete Snapshots
  • Backup Procedures
  • Recovery

Placeholders

Replace the placeholders below with the appropriate values for your setup:

• Devices

  • Block device: <device> (e.g., /dev/sda)
  • Source device to replace: <source-device> (e.g., /dev/sdb)
  • Target device: <target-device> (e.g., /dev/sdc)
  • UUID: <uuid> (e.g., a1b2c3d4-e5f6-7890-abcd-ef1234567890)

• Paths

  • Mount point: <mountpoint> (e.g., /mnt/media)
  • Subvolume name: <subvolume> (e.g., root, home, backups, snapshots)
  • Subvolume ID: <subvolume-id> (e.g., 257)
  • Snapshot label: <snapshot-label> (e.g., 2024-09-15)

BTRFS Command Shorthands

Most btrfs subcommands accept shortened aliases. The table below lists the common ones used throughout this document.

Long form	Short form
btrfs filesystem	btrfs fi
btrfs filesystem show	btrfs fi show
btrfs filesystem usage	btrfs fi usage
btrfs filesystem df	btrfs fi df
btrfs filesystem resize	btrfs fi resize
btrfs filesystem defragment	btrfs fi defrag
btrfs subvolume	btrfs sub
btrfs subvolume list	btrfs sub list
btrfs subvolume snapshot	btrfs sub snap
btrfs subvolume delete	btrfs sub del
btrfs subvolume get-default	btrfs sub get-default
btrfs subvolume set-default	btrfs sub set-default
btrfs device	btrfs dev
btrfs device add	btrfs dev add
btrfs device usage	btrfs dev usage
btrfs device stats	btrfs dev stats
btrfs balance start	btrfs bal start
btrfs balance status	btrfs bal status
btrfs balance cancel	btrfs bal cancel
btrfs inspect-internal	btrfs insp

Information on Filesystem

Show Basic Filesystem Information

Display basic information (size, IDs, paths, etc.) for the specified mountpoint:

btrfs fi show <mountpoint>

Display detailed usage information

To show detailed usage information (allocated, unallocated, free, used, etc.) for the specified mountpoint:

btrfs fi usage <mountpoint>

Display detailed usage information as a table

btrfs fi usage -T <mountpoint>

• -T The tabular flag gives you a nice grid that shows exactly how much Data, Metadata, and System space is allocated per device.

Display Detailed Allocation Information

View block groups and used space:

btrfs fi df <mountpoint>

Get Detailed Device Usage Statistics

Physical size, unallocated space, RAID levels, etc.:

btrfs device usage <mountpoint>

Scan and Display BTRFS Information

Scan all devices or a specific drive:

btrfs device scan <device>

Retrieve Statistics and Error Information

Read errors, write errors, flush errors, etc.:

btrfs device stats <mountpoint>

List BTRFS Subvolumes

btrfs subvolume list <mountpoint>

Default Subvolume

Check if a non-standard subvolume is set as the default:

btrfs subvol get-default <mountpoint>
btrfs subvol list <mountpoint>

Change the default subvolume:

btrfs subvol set-default <subvolume-id> <mountpoint>

Verify Current Cache Version

Check if your filesystem is using cache V1 by device:

btrfs inspect-internal dump-super -f <device> | grep cache_generation

By UUID:

btrfs inspect-internal dump-super -f $(blkid -U <uuid>) | grep cache_generation

• If cache_generation is present, cache V1 is in use. If absent, the filesystem is already using V2.

Drive Manipulation

Mount Whole Drive

mount UUID=<uuid> <mountpoint>

Mount Subvolume by Name

mount UUID=<uuid> -o subvol=<subvolume> <mountpoint>

Mount Subvolume by ID

btrfs subvol list /
mount -o subvolid=<subvolume-id> /dev/disk/by-uuid/<uuid> <mountpoint>

Add a New Drive

btrfs device add <device> <mountpoint>

Resize Filesystem

Grow the filesystem on a specific device to its maximum:

btrfs filesystem resize 1:max <mountpoint>

Create Subvolumes

btrfs subvol create <mountpoint>/<subvolume>

Replace Drives

Start the replacement process:

Copies data from the old drive to the new drive while the filesystem remains mounted:

btrfs replace start <source-device> <target-device> <mountpoint>

• <source-device>: Drive to be replaced.
• <target-device>: Drive to replace it with.
• <mountpoint>: Mount point of the BTRFS filesystem.

Monitor the progress:

btrfs replace status <mountpoint>

Monitor progress interactively:

btrfs replace status -i <mountpoint>

• -i: Updates progress in real time.

Notes:

• btrfs replace works on a live mounted filesystem — no unmounting required.
• Useful for both failing drive replacement and capacity upgrades.
• Ensure the target drive has enough space to accommodate the source data.

Filesystem Manipulation

Upgrading Btrfs Block Group Cache to V2

Non-root filesystems (running system):

mount -o remount,clear_cache,space_cache=v2 <mountpoint>

Root filesystem (running system):

1. Check if using cache V1:

   btrfs inspect-internal dump-super -f <device> | grep cache_generation
   

2. Enable cache V2 via GRUB:

   nano /etc/default/grub
   # Add to GRUB_CMDLINE_LINUX_DEFAULT or GRUB_CMDLINE_LINUX:
   # rootflags=clear_cache,space_cache=v2
   

   Example:

   GRUB_CMDLINE_LINUX_DEFAULT="quiet splash rootflags=clear_cache,space_cache=v2"
   

   update-grub
   reboot
   

3. Verify the change:

   btrfs inspect-internal dump-super -f <device> | grep cache_generation
   

4. Remove clear_cache from GRUB after confirming:

   nano /etc/default/grub
   # Remove clear_cache from rootflags, then:
   update-grub
   

From a live system:

apt update
apt install btrfs-progs
lsblk -o NAME,UUID
blkid
mount -o clear_cache,space_cache=v2 /dev/disk/by-uuid/<uuid> <mountpoint>
btrfs inspect-internal dump-super -f /dev/disk/by-uuid/<uuid> | grep cache_generation
umount <mountpoint>

Defrag

btrfs filesystem defrag -r -v -clzo <mountpoint>

• -r: Recursive.
• -v: Verbose.
• -clzo: Optional LZO compression to save space.

Balances

Full balance on nearly empty block groups:

btrfs balance start --full-balance -dusage=0 -musage=0 <mountpoint>

• --full-balance: Default but with a warning if not specified.
• -dusage=0: Only balance data block groups that are ~0% full.
• -musage=0: Only balance metadata block groups that are ~0% full.

Full balance on partially used block groups:

btrfs balance start --full-balance -dusage=50 -musage=50 <mountpoint>

• -dusage=50: Include data block groups less than 50% full.
• -musage=50: Include metadata block groups less than 50% full.

Balance data in the background:

btrfs balance start --bg -d <mountpoint>

Balance metadata in the background:

btrfs balance start --bg -m <mountpoint>

Balance data and metadata in the background:

btrfs balance start --bg --full-balance -dusage=0 -musage=0 <mountpoint>

Balance a limited number of chunks:

btrfs balance start --bg -dlimit=100 <mountpoint>

Cancel a balance:

btrfs balance cancel <mountpoint>

Monitor balance status:

btrfs balance status <mountpoint>

Scrub

Start a scrub

The scrub operation verifies data integrity against checksums

btrfs scrub start <mountpoint>

Check scrub status:

btrfs scrub status <mountpoint>

Cancel a scrub:

btrfs scrub cancel <mountpoint>

Snapshots

Create Snapshots

1. Mount the snapshots subvolume:

   mount UUID=<uuid> -o subvol=snapshots <mountpoint>
   

2. Create a snapshot:

   btrfs subvolume snapshot <source-subvolume> "<mountpoint>/<snapshot-label>"
   

3. Unmount after creating:

   umount <mountpoint>
   

Delete Snapshots

1. Mount the snapshots subvolume:

   mount -o subvol=snapshots /dev/disk/by-uuid/<uuid> <mountpoint>
   

2. List available snapshots:

   btrfs subvol list <mountpoint>
   

3. Delete the desired snapshot:

   btrfs subvolume delete <mountpoint>/<snapshot-label>
   

4. Unmount after deleting:

   umount <mountpoint>
   

Backup Procedures

Snapshot backup procedure:

1. Mount snapshot location:

   mount UUID=<uuid> -o subvol=snapshots <mountpoint>
   

2. Create snapshots for the desired subvolumes:

   btrfs subvolume snapshot / "<mountpoint>/root/<snapshot-label>"
   btrfs subvolume snapshot /home "<mountpoint>/home/<snapshot-label>"
   btrfs subvolume snapshot <source-subvolume> "<mountpoint>/<subvolume>/<snapshot-label>"
   

3. Unmount after creating snapshots:

   umount <mountpoint>
   

Recovery

1. Mount a Subvolume with Recovery Options:

   mount -o recovery,subvol=<subvolume> UUID=<uuid> <mountpoint>
   

2. Clear Cache During Mount:

   mount -o clear_cache,subvol=<subvolume> UUID=<uuid> <mountpoint>
   

3. Data Restoration with btrfs restore:

   btrfs restore -D <device>