This is a draft guide for using btrfs-convert to convert Debian 12 root ext4 systems to btrfs.

I keep meaning to post this, so figured I might as well do it before it attains perfection.

Background: Successfully did a btrfs-convert on two Debian 12 installs around September 2024 and have had no issues since.

The ArchBang instructions were an initial attempt to develop a workflow to later test with Arch and improve ArchWiki, but that whole thing moves too quickly and I don't think anyone there cares about btrfs-convert.

Follow these instructions at your own risk. You must test them in a virtual environment first, preferably several times.

mkfs.btrfs is historically the more reliable method to use. Issues with btrfs-convert have existed in the past so perform at your own risk.

Debian 12

1. btrfs-convert /dev/vda1
   1. mount /dev/vda1 /mnt
   2. cd /mnt
   3. ls
   4. btrfs subvolume snapshot . @rootfs
   5. ls
   6. cd /
   7. umount /mnt
2. mount -o subvol=@rootfs /dev/vda1 /mnt
   1. cd /mnt
   2. mount /dev/xxxn boot/
   3. mount --bind /dev dev/
   4. mount --bind /proc proc/
   5. mount --bind /sys sys/
3. chroot /mnt
4. nano /etc/fstab OR vi /etc/fstab
   1. #Comment out the line containing / after UUID b. Add /dev/xxx1 / btrfs noatime,compress=zstd:1,subvol=@rootfs 0 0
5. update-initramfs -u
6. grub-mkconfig -o /boot/grub/grub.cfg
   1. /boot/grub/grub.cfg should now have the new UUID of the btrfs partition (see blkid for UUIDs)
7. grub-install /dev/xxx (WITHOUT the number)
8. exit / ctrl-d from chroot
9. cd /
10. umount -R /mnt and reboot into btrfs system

ArchBang (2024)

---

From a live USB of the same system, convert, create subvolumes, and move contents of /home to the new @home subvolume:

ALSO before you start, BACKUP (preferably to two different storage devices) and make sure your system is up-to-date (especially btrfs-progs). ASSUME the following process will fail on you and that you'll need to reinstall everything and restore from backups!

Convert partition from ext4 to btrfs:

1. btrfs-convert /dev/vda1
2. mount /dev/vda1 /mnt
3. cd /mnt
4. ls
5. btrfs subvolume snapshot . @rootfs
6. btrfs subvolume create @home
7. mv home/* @home/
8. ls
9. cd /
10. umount /mnt

REMEMBER to not delete ext2_saved or run btrfs balance, or btrfs filesystem defragment until you're certain you don't need to rollback with btrfs-convert -r /dev/xxx#!!

Remount new root subvolume, mount, chroot and update initramfs and grub:

1. mount -o subvol=@rootfs /dev/vda1 /mnt
2. cd /mnt
3. mount /dev/xxx# boot/ ([)if on a separate partition; else ignore this step)
4. mount --bind /dev dev/
5. mount --bind /proc proc/
6. mount --bind /sys sys/

chroot & fstab:

1. chroot /mnt
2. nano /etc/fstab OR vi /etc/fstab
3. #Comment out the existing line containing / in fstab (UUIDs will be the same - using /dev/xxx# temporarily to get this going will also work fine so long as your drive assignments won't change)
4. Add /dev/xxx# / btrfs noatime,compress=zstd:1,subvol=@rootfs 0 0
5. Add /dev/xxx# /home btrfs noatime,compress=zstd:1,subvol=@home 0 0

Update initramfs, grub.cfg, and install grub:

1. mkinitcpio -g /boot/initTAB COMPLETE.img
2. grub-mkconfig -o /boot/grub/grub.cfg
3. /boot/grub/grub.cfg should now have the new UUID of the btrfs partition (see blkid for UUIDs)
4. grub-install /dev/xxx (without the number of the device)

Finishing touches:

1. exit or ctrl-d from chroot
2. cd / to get out of /mnt so we can umount
3. umount -R /mnt (-R = recursive) and reboot into btrfs system

Rollback instructions

Even if you've gone through with all of these steps, you can still do a rollback. You will however need to repeat the grub-install /dev/### step after performing btrfs-convert -r /dev/xxx#. Don't forget to mount dev/proc/sys again and chroot. The mkinitcpio step won't be necessary, nor grub-mkconfig. Only grub-install will be required before you unmount and reboot.

ext2_saved removal and clean-up

Head back into a live USB boot, mount the btrfs partition, rm -r every directory that isn't @rootfs or @home and then finally finish it off with btrfs subvolume delete ext2_saved.

While rm will still work on subvolumes, it's better practice to use btrfs subvolume delete so that you can be sure you're removing subvolumes and not regular directories.

cd / && umount /mnt, reboot and you're finally all done! However, be sure to keep reading and learning about how to maintain BTRFS subvolumes. DO NOT run defrag on volumes that contain snapshots or you'll likely soon hit the 100% usage issue! It's best to run defrag in a more targeted manner, a directory at a time.

Other maintenance basics

• Don't fill your filesystem up to 100%.
• Run a filtered balance every now and then.
• Learn to make use of compression and snapshots, and backup said snapshots
• with btrfs-send and borg backup.
• Don't use RAID until you have a good backup regimen in place, because RAID is not a backup.
• BTRFS is not for beginners. Be prepared to remain patient and read before you execute.
• Never run btrfs check --repair unless you're ready to destroy your filesystem.
• Carefully read https://dontasktoask.com to get the most out of IRC support. esr's smart questions is also a useful guide to follow if you want the best help available.