Btrfs/Space Cache

From Forza's ramblings
(Redirected from Btrfs/Free-Space-Tree)

Btrfs Space Cache[edit | edit source]

Picture of a squirrel.
Red squirrel (Sciurus vulgaris) searching for cached nuts.

Copy-on-Write (CoW) means that the filesystem never overwrites existing data in-place, but instead it writes new data on empty locations. Once the data is written it updates its metadata to point to the newly written data. This means if there is a crash or power outage, the filesystem will remain intact. Either all the old data is still intact or all of the new data.

Because of the need to quickly find empty areas to write to, it is very important that Btrfs keeps track on where there is free space to write new data, or the performance would suffer. Btrfs solves this by creating a special cache of all the free space on the filesystem.

Free Space Tree - aka "space_cache=v2"[edit | edit source]

There are two versions of this free space cache, The original v1 and then the new modern v2, which is called free space tree.

On very large filesystems (many terabytes) and with certain workloads, the performance of the v1 space cache may degrade drastically. This is why the new v2 implementation was created. It uses a new B-tree called the free space tree.

Starting with btrfs-progs 5.15, the free space tree is the default for all newly created filesystems.

Switch to Free Space Tree[edit | edit source]

To change to use the Free Space Tree you have to unmount the filesystem, remove the previous space cache, then mount it with the space_cache=v2 mount option. This will be a permanent change and Btrfs will use the new Free Space Tree on all future mounts once enabled.

# umount /mnt/btrfs 
# btrfs check --clear-space-cache v1 /dev/device
# mount /dev/device /mnt/btrfs -o space_cache=v2

You only need to run btrfs check --clear-space-cache v1 /dev/device on one of the disks in a multiple disk filesystem.

If you want to change your root filesystem you have to boot with a Live USB stick to be able to mount the filesystem with the above options. The Fedora Workstation Live DVD is a good choice since it has up-to-date Linux kernels and btrfs-progs.

Switching back to Space Cache from Free Space Tree can be done in the same was as before:

# umount /mnt/btrfs 
# btrfs check --clear-space-cache v2 /dev/device
# mount /dev/device /mnt/btrfs -o space_cache=v1

mkfs.btrfs with Free Space Tree[edit | edit source]

Use the -R free-space-tree option to enable Free Space Tree as default for your new filesystem. Then you do not have to use the method above to clear the old Space Cache to switch to the Free Space Tree.

# mkfs.btrfs -R free-space-tree -L my-btrfs /dev/vdb1
btrfs-progs v5.13.1 
See for more information.

Label:              my-btrfs
UUID:               80014f0a-dd1d-4f09-ab34-7adeb27585df
Node size:          16384
Sector size:        4096
Filesystem size:    512.00GiB
Block group profiles:
  Data:             single            8.00MiB
  Metadata:         DUP               1.00GiB
  System:           DUP               8.00MiB
SSD detected:       no
Zoned device:       no
Incompat features:  extref, skinny-metadata
Runtime features:   free-space-tree 
Checksum:           crc32c
Number of devices:  1
   ID        SIZE  PATH
    1   512.00GiB  /dev/vdb1