Btrfs filesystem cheatsheet

By , last updated September 30, 2019

Btrfs is a relatively new 5th generation filesystem, similar to ZFS. For more information about those generations and filesystems, read this article over at Ars Technica.

This page will contain a simple reference for commands I might find useful.

Create new mirrored filesystem (RAID1)

# Mirrored metadata and mirrored data.
mkfs.btrfs -m raid1 -d raid1 <devices>

# Btrfs RAID1 example
mkfs.btrfs -m raid1 -d raid1 /dev/sdc /dev/sdd

This will create a mirrored filesystem. It is possible to use more than 2 drives, and then the data will be balanced between the drives. There are only two copies of the data, regardless on how many drives you have.

Mounting btrfs filesystems

By device

A btrfs default volume can be mounted by either using the drives you created the devices from (/dev/sdc and /dev/sdd in the example above).

# Mount btrfs default / root volume with device.
# These are
mount /dev/sdc /btrfs
mount /dev/sdd /btrfs

By UUID

It’s also possible to mount the volume by using the UUID identifier for the device.

It can be found by either blkid or btrfs filesystem show.

# Find btrfs filesystem with blkid
blkid | grep btrfs
/dev/sdc: UUID="aa0c6d19-1590-434f-ba9b-ecb79237005f" TYPE="btrfs"
/dev/sdd: UUID="aa0c6d19-1590-434f-ba9b-ecb79237005f" TYPE="btrfs"

# btrfs filesystem show
btrfs filesystem show
Label: none  uuid: aa0c6d19-1590-434f-ba9b-ecb79237005f
        Total devices 2 FS bytes used 2.11TiB
        devid    1 size 5.46TiB used 2.11TiB path /dev/sdc
        devid    2 size 5.46TiB used 2.11TiB path /dev/sdd

# Mount by UUID
mount /dev/disk/by-uuid/aa0c6d19-1590-434f-ba9b-ecb79237005f /btrfs
# or
mount --uuid aa0c6d19-1590-434f-ba9b-ecb79237005f /btrfs

In btrfs fstab with UUID

Identical to other filesystems mounting as UUID.

# Mount btrfs by UUID
UUID=aa0c6d19-1590-434f-ba9b-ecb79237005f /bigfs btrfs noatime 0 2

Create btrfs subvolumes

A subvolume can have nested subvolumes, and snapshots of the parent subvolume will contain the same atomic data as the parent subvolume.

cd /btrfs
btrfs subvolume create pictures

Mounting btrfs subvolumes

By mount

# Mount by device
mount -t btrfs -o subvol=pictures /dev/sdc /home/user/pictures

# Mount by UUID
mount -t btrfs -o subvol=pictures -U aa0c6d19-1590-434f-ba9b-ecb79237005f /home/user/pictures

With fstab

UUID=aa0c6d19-1590-434f-ba9b-ecb79237005f /home/user/pictures btrfs noatime,subvol=pictures 0 0

Create btrfs snapshots

Snapshots are what the name implies, a snapshot of the state of the volume at the time it was taken. The operation is atomic, meaning the whole filesystem will be in a consistent state when it’s taken.

There are both read/write snapshots, and readonly snapshots.

# Read-write snapshot
# Make a directory where the snapshots will reside
mkdir -p /btrfs/pictures-snapshots

# Make snapshot
btrfs subvolume snapshot /btrfs/pictures /btrfs/pictures-snapshot/snapshot_of_pictures

Readonly snapshot. Use the parameter -r to create a readonly snapshot.

btrfs subvolume snapshot -r /btrfs/pictures /btrfs/pictures-snapshot/snapshot_of_pictures

Delete btrfs snapshots

# Delete snapshot (which is a subvolume)
btrfs subvol delete /btrfs/pictures-snapshot/snapshot_of_pictures

Create btrfs snapshots with cron script

#!/bin/bash

d=`date '+%Y-%m-%d_%H-%M'`

vol=/btrfs/pictures
snapdir=$vol/.snapshots
mkdir -p $snapdir
snap=$snapdir/snapshot_$d

/sbin/btrfs subvolume snapshot $vol $snap

Bash script with arguments (better suited for cron)

#!/bin/bash
# Save as makesnapshot.sh

vol=$1

if [[ -z $vol ]]
then
    echo "Usage: ./makesnapshot.sh <btrfs_subvolume>"
    exit
fi

d=`date '+%Y-%m-%d_%H-%M'`

snapdir=$vol/.snapshots
mkdir -p $snapdir
snap=$snapdir/snapshot_$d

/sbin/btrfs subvolume snapshot $vol $snap

As always, we must test the script

# Test the script
./makesnapshot.sh /bigfs/bilder
Create a snapshot of '/btrfs/pictures' in '/btrfs/pictures/.snapshots/snapshot_2015-03-15_21-51'

List snapshot properties

Snapshots and volumes can have properties, and one of those are read/write and readonly. This is not a very well documented feature.

Properties are available per type (family), under these shortcuts: s[ubvol], f[ilesystem], i[node] and d[evice].

# List all properties for a volume
btrfs property list /btrfs/
    ro Set/get read-only flag of subvolume.
    label Set/get label of device.
    compression Set/get compression for a file or directory

# Get btrfs readonly flag
btrfs property get /btrfs ro
    ro=false

# Set btrfs readonly flag
btrfs property set /btrfs ro true

# Check if it's readonly
btrfs property get /btrfs ro
    ro=true

Professional Software Developer, doing mostly C++. Connect with Kent on Twitter.