homelab/active/software_btrfs/btrfs.md

BTRFS

• BTRFS
  • Naming Conventions
  • Creating an Array
  • Converting an Array Between RAID Versions
  • Mounting the Array
  • Adding Disks
  • Replacing a Disk
  • Scrubbing the Array
  • Creating Subvolumes
  • Monitoring Usage
  • Monitoring Disk Health
  • Defragmenting and Compressing
  • Converting ext4 to btrfs

Oracle has decent docs here

You'll also want to read about btrfs compression

Naming Conventions

poolX is my naming convention for data pools. pool0 is the first pool you create.

backupX is my naming convention for backup pools. backup0 is hte first backup pool you create.

Creating an Array

# At any point you can check the status of an array by referencing any member
btrfs filesystem show /dev/vdb

# Raid0
mkfs.btrfs --data raid0 --metadata raid0 /dev/vdb /dev/vdc
btrfs device scan

# Raid1
mkfs.btrfs --data raid1 --metadata raid1 /dev/vdb /dev/vdc
btrfs device scan

# Raid1c3
mkfs.btrfs --data raid1c3 --metadata raid1c3 /dev/vdb /dev/vdc /dev/vdd
btrfs device scan

# Raid10
mkfs.btrfs --data raid10 --metadata raid10 /dev/vdb /dev/vdc /dev/vdd /dev/vde
btrfs device scan

Label your arrays for easier identification in btrfs filesystem information commands

btrfs filesystem label /btrfs/pool0 pool0

Converting an Array Between RAID Versions

# Convert to raid1
# -dconvert == "data convert"
# -mconvert == "metadata convert"
btrfs balance start -dconvert=raid1 -mconvert=raid1 /btrfs/pool0
btrfs balance status

Mounting the Array

One off

# Create a mount point
mkdir /btrfs/pool0

# List the filesystem UUID
lsblk --fs

# Mount the top level subvolume
mount UUID=xxxxx-xxxxx-xxxxx /btrfs/pool0 -o subvolid=5

# Mount with better SSD support
mount UUID=xxxxx-xxxxx-xxxxx /btrfs/pool0 -o subvolid=5,ssd

# Mount with auto defragmentation for HDD support
mount UUID=xxxxx-xxxxx-xxxxx /btrfs/pool0 -o subvolid=5,autodefrag

# Mount a subvolume
mount UUID=xxxxx-xxxxx-xxxxx /btrfs/pool0 -o subvol=home

# Inspect
btrfs filesystem show /btrfs/pool0

In fstab

UUID=btrfs_uuid  /btrfs/pool0  btrfs  defaults 0 0

Adding Disks

# Add a disk
btrfs device add /dev/vdd /btrfs/pool0

# Balance the array
btrfs balance start /btrfs/pool0

# Watch the expansion
btrfs filesystem usage /btrfs/pool0

Replacing a Disk

# Remove a disk from the array
# This may take a while, as btrfs will rebalance the array during this process
btrfs device remove /dev/vdb /btrfs/pool0

# You can watch the device "used" data drain with
watch btrfs filesystem show /btrfs/pool0/

# Add the new device
# Again, this may take a while while btrfs rebalances.
btrfs device add /dev/vdg /btrfs/pool0

Scrubbing the Array

# Start a scrub to check for errors
# -B prevents the process from going to the background
# -d prints stats for each device
btrfs scrub start -Bd /btrfs/pool0

# Check the status of a scrub
btrfs scrub status /btrfs/pool0

# Watch for disk failures
dmesg | grep btrfs

Creating Subvolumes

# Create a new subvolume (make sure to mount /btrfs as subvolid=5)
btrfs subvolume create /btrfs/pool0

# List all subvolumes under a path
btrfs subvolume list -o /btrfs/pool0

# Delete a subvolume
btrfs subvolume delete /btrfs/pool0

Monitoring Usage

# Quick info for all btrfs arrays
btrfs filesystem show

# Show usage for a specific array
btrfs filesystem usage /btrfs/pool0

# Quick command to filter for data used
btrfs filesystem usage /btrfs/pool0 | grep 'Data.*Used'

Monitoring Disk Health

https://www.dotlinux.net/blog/how-to-configure-smartd-and-be-notified-of-hard-disk-problems-via-email/#installing-smartd-smartmontools

# btrfs device stats shows any errors
# Grep for any line not ending in "0"
btrfs device stats /btrfs/pool0 | grep -vE ' 0$'

# Show the device IDs for the mounted filesystem
btrfs filesystem show /btrfs/pool0

# Delete a device (with ID 8, for example)
btrfs device delete 8 /btrfs/pool0

# Add a device to the array
btrfs device add /dev/vdi1 /btrfs/pool0

# Rebalance the array
btrfs balance start --background --full-balance /btrfs/pool0

# Check the status
btrfs balance status /btrfs/pool0

Defragmenting and Compressing

# Defrag a filesystem
btrfs filesystem defragment /btrfs/pool0

# Defrag and apply compression
# zstd:20 is currently the best compression algorithm
btrfs filesystem defragment -c zstd:20 /btrfs/pool0

Converting ext4 to btrfs

# Unmount and then run btrfs-convert
umount /path/to/mount
btrfs-convert /dev/sdX1