Btrfs Space Cache[edit | edit source]
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 CoW, 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. For now, the default is still the original space cache.
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 B-trees called the free space tree.
The default is still to use V1. While this is mostly for legacy reasons, myself and others always recommend using v2. V2 was introduced in 13 March 2016, and it has plenty of real world use without issues.
There is ongoing work to switch to v2 by default.
Switch to space_cache=v2[edit | edit source]
To change to space_cache v2 you have to unmount the filesystem and mount it with the
space_cache=v2 mount option.
# umount /mnt/btrfs # btrfs check --clear-space-cache v1 /dev/device # mount /dev/device /mnt/btrfs -o space_cache=v2
You only need to mount the filesystem with
space_cache=v2 once. The filesystem will continue to use it for subsequent mounts.
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 USB stick to be able to mount the filesystem with the above options.
Once enabled, the v2 space cache will always be used and cannot be disabled unless it is cleared using
clear_cache,nospace_cache mount option.
# mount /dev/device /mnt/btrfs -o clear_cache,nospace_cache
mkfs.btrfs with space_cache=v2[edit | edit source]
It is possible to create a new Btrfs filesystem with space_cache v2 as default. Use the
-R free-space-tree option.
# mkfs.btrfs -R free-space-tree -L my-btrfs /dev/vdb1
btrfs-progs v5.13.1 See http://btrfs.wiki.kernel.org 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 Devices: ID SIZE PATH 1 512.00GiB /dev/vdb1