This collates the lessons I have learned when I attempted to convert the root filesystem to btrfs on my RaspberryPi.
First things first – it is NOT just run the btrfs-convert and change a couple of bits of config. I initially thought it was, and this bit me quite spectacularly. I’ve now spent a few hours getting this working, so learn from my experience.
I should note that my work comes from digging about on the internet. These posts helped point the way:
Steps:
- You will need to be able to work with two operating systems which may mean you need use a USB -> SD Card converter.
- Check whether btrfs is being loaded on boot.
If it isn’t it will need adding FIRST. Do not go any further until the module is included in the initramfs.
- Check in boot log
- Run this command:
dmesg | grep -i btrfs
- You are looking for this in the output:
[ 2.651955] Btrfs loaded, zoned=no, fsverity=no
- Check in kernel
- Can see the module here:
lsmod | grep -i btrfs
- Output should be similar to:
btrfs 1630208 1
xor 12288 1 btrfs
raid6_pq 106496 1 btrfs
- Check whether btrfs is in the initramfs
- Run this:
lsinitramfs /boot/initrd.img-$(uname -r) | grep btrfs
- You are looking specifically for these lines:
usr/lib/modules/6.12.75+rpt-rpi-v8/kernel/fs/btrfs
usr/lib/modules/6.12.75+rpt-rpi-v8/kernel/fs/btrfs/btrfs.ko.xz
- If these lines are NOT appearing then you MUST do the following:
- Add BTRFS into the initramfs modules:
echo 'btrfs' | sudo tee -a /etc/initramfs-tools/modules
- Update Initramfs
sudo update-initramfs -c -k $(uname -r)
- You can check the the initramfs is now correct using the lsinitramfs command above.
- Reboot your system
- Check for the module in the boot log AND the kernel as before.
- Now you can install btrfs:
sudo apt install btrfs-progs
- The system is now prepared – shut it down and BACKUP the SD Card.
Everything from here on could lead to a broken system so it is at your own risk. If you can’t risk having a broken system, and starting everything again from scratch, do not go any further.
- Boot from another SD Card. This system will need btrfs installed on it obviously.
- Check the root volume for errors:
sudo fsck -f /dev/sdb2
- Convert the root volume:
sudo btrfs-convert /dev/sdb2
- Obviously, this will take a while
- It will finish, with output similar to:
btrfs-convert from btrfs-progs v6.14
Source filesystem:
Type: ext2
Label: rootfs
Blocksize: 4096
UUID: ed6c7f1b-238b-41a1-b4b6-7bcdef3270fe
Target filesystem:
Label:
Blocksize: 4096
Nodesize: 16384
UUID: cd4d1c9c-8fe9-4fac-a8e5-1e828ef54432
Checksum: crc32c
Features: extref, skinny-metadata, no-holes, free-space-tree (default)
Data csum: yes
Inline data: yes
Copy xattr: yes
Reported stats:
Total space: 63319310336
Free space: 50360090624 (79.53%)
Inode count: 3813760
Free inodes: 3590302
Block count: 15458816
Create initial btrfs filesystem
Create ext2 image file
Create btrfs metadata
Copy inodes [o] [ 223370/ 223458]
Free space cache cleared
Conversion complete
- At this point, conversion is complete.
- Perform a sanity mount of this converted filesystem:
sudo mount /dev/sdb2 /mnt
- Assuming it mounts fine we want to fix fstab:
vi /mnt/etc/fstab
- It will look something like this:
proc /proc proc defaults 0 0
PARTUUID=3ae81c03-01 /boot/firmware vfat defaults 0 2
PARTUUID=3ae81c03-02 / ext4 defaults,noatime 0 1
- Convert the line for / to use btrfs.
NB The PARTUUIDs did not change for me.
- Will now look like this:
proc /proc proc defaults 0 0
PARTUUID=3ae81c03-01 /boot/firmware vfat defaults 0 2
PARTUUID=3ae81c03-02 / btrfs defaults,noatime 0 1
- Unmount converted root.
sudo umount /mnt
- Mount the boot filesystem
sudo mount /dev/sdb1 /mnt
- Update boot options:
sudo vi /mnt/cmdline.txt
- Should look like this:
console=serial0,115200 console=tty1 root=PARTUUID=3ae81c03-02 rootfstype=ext4 fsck.repair=yes rootwait quiet splash plymouth.ignore-serial-consoles ds=nocloud;i=rpi-imager-1777239363059 cfg80211.ieee80211_regdom=GB
- Change rootfstype to btrfs.
- Will now look like this:
console=serial0,115200 console=tty1 root=PARTUUID=3ae81c03-02 rootfstype=btrfs fsck.repair=yes rootwait quiet splash plymouth.ignore-serial-consoles ds=nocloud;i=rpi-imager-1777239363059 cfg80211.ieee80211_regdom=GB
- Everything should now be ready. Shut everything down put you SD Card in and cross your fingers. It should boot.
One the system boots you should see further entries related to btrfs in the boot log if you look using dmesg | grep -i btrfs
[ 0.000000] Kernel command line: coherent_pool=1M 8250.nr_uarts=1 snd_bcm2835.enable_headphones=0 cgroup_disable=memory numa_policy=interleave nvme.max_host_mem_size_mb=0 snd_bcm2835.enable_headphones=1 snd_bcm2835.enable_hdmi=1 snd_bcm2835.enable_hdmi=0 numa=fake=2 system_heap.max_order=0 iommu_dma_numa_policy=interleave smsc95xx.macaddr=E4:5F:01:05:57:6B vc_mem.mem_base=0x3ec00000 vc_mem.mem_size=0x40000000 console=ttyS0,115200 console=tty1 root=PARTUUID=3ae81c03-02 rootfstype=btrfs fsck.repair=yes rootwait quiet splash plymouth.ignore-serial-consoles ds=nocloud;i=rpi-imager-1777239363059 cfg80211.ieee80211_regdom=GB
[ 2.689648] Btrfs loaded, zoned=no, fsverity=no
[ 2.994418] BTRFS: device label rootfs devid 1 transid 209 /dev/mmcblk0p2 (179:2) scanned by mount (212)
[ 2.995544] BTRFS info (device mmcblk0p2): first mount of filesystem cd4d1c9c-8fe9-4fac-a8e5-1e828ef54432
[ 2.995568] BTRFS info (device mmcblk0p2): using crc32c (crc32c-generic) checksum algorithm
[ 3.040169] BTRFS info (device mmcblk0p2): enabling ssd optimizations
[ 3.040186] BTRFS info (device mmcblk0p2): turning on async discard
[ 3.040191] BTRFS info (device mmcblk0p2): enabling free space tree
Once you are happy everything is alright, you can delete the failback subvolume:
sudo btrfs subvolume delete /ext2_saved
Should see similar to:
Delete subvolume 256 (no-commit): '//ext2_saved'
And that should be it root is converted – enjoy your btrfs based RaspberryPi system.
Things I discovered.
- If you are an idiot like me, you can copy an initramfs of the same kernel (with the module) to the boot volume.
The one that was important to me was the one called initramfs8 in that directory.
- If you’ve stuffed up the cmdline.txt file you can also copy that.
- Remember that you do have to correct the PARTUUID when you do this (I didn’t).