Here is a simple tutorial guide of system migration from ext4 to btrfs.
For the simplicity and versatility of this guide, we assume the original system uses separate root and home partitions. (For more complicated case etc., please create a separate wiki page linked from here. Please keep this page simple.) The converted btrfs has root and home directory contents in the subvolume.
Although you can boot the system with a USB memory stick with Debian installer and do essentially the same to migrate system to btrfs, a safer strategy to migrate a system to btrfs can go as follows:
- Step 0: Dual-boot preparation
- Step 1: Migration of the root filesystem to Btrfs
- Step 1.1: Do it on the secondary system as practice
- Step 1.2: Do it on the primary system for real
- Step 2: Workaround to use subvol=@ as the system root filesystem on Debian
- Step 2.1: Do it on the secondary system as practice
- Step 2.2: Do it on the primary system for real
- Step 3: Use snapshot with btrfs
Dual boot preparation
Let's make a system dual bootable by installing a small secondary system onto an ext4 filesystem using debian-installer.
If there is no empty space on disk, use program such as gparted to make it before running debian-installer.
- This newly created secondary system doesn't need GUI packages.
- This newly created secondary system needs 'btrfs-utils' and 'grub-efi' packages.
- This newly created system doesn't need to mount home partition but it can't harm to do so.
- This may share its EFI partition with the primary Linux system.
- Set up the secondary Linux system for dual-boot with grub.
Migration of the root filesystem to Btrfs
- Boot the primary Linux system.
Convert the partition containing the secondary Linux system from ext4 to btrfs using btrfs-convert.
- Check the new UUID of the partition containing the secondary Linux system and update the UUID of configuration files.
Update /etc/fstab of the secondary Linux system.
Change from ext4 errors=remount-ro to btrfs defaults
Change insmod ext2 to insmod btrfs
Execute sudo update-grub2
- Confirm the successful booting of the secondary Linux system on btrfs.
- Boot the secondary Linux system and do the same to migrate the primary Linux system to btrfs.
This converts the top level subvolume (id=5) of the btrfs as the new system root filesystem. Debian grub auto configuration script (as of 2021-march) is compatible with this usage.
Workaround to use subvol=@ as the system root filesystem on Debian
Migrate the system root filesystem to /@ for the primary Linux system.
sudo btrfs subvolume snapshot / /@
sudo btrfs subvolume set-default /@
- Boot the secondary Linux system.
Remove original files from / (excluding ones under /@) for the primary Linux system.
Mount the primary Linux system on /mnt
Move to /mnt/ by cd /mnt.
Add relative symlinks in /mnt for the primary Linux system as workaround.
vmlinuz -> @/vmlinuz
vmlinuz.old -> @/vmlinuz.old
initrd.img -> @/initrd.img
initrd.img.old -> @/initrd.img.old
boot -> @/boot
etc -> @/etc
lib -> @/lib
usr -> @/usr
var -> @/var
Execute sudo update-grub2
The above mentioned workaround symlinks may be useful for Debian grub system to detect other distributions using @ subvolume as the root filesystem.
You can avoid sudo btrfs subvolume set-default @ by explicitly setting subvol=@,defaults in /etc/fstab or adding kernel boot parameter rootflags=subvol=@. The kernel can be booted without symlinks as long as /boot/grub/grub.cfg lists the full file path to vmlinuz and initrd.img. These workaround symlinks are there to fool auto-detection of the installed system by /etc/grub.d/30_os-prober (Debian bulleseye/testing, March/2021) for grub.cfg.
Both Suse and Ubuntu seem to use subvol=@ for root filesystem for btrfs.
Ubuntu's current /etc/grub.d/30_os-prober checks @ and bind mount it as root if it exists to avoid missing the system installation.
Keeping the root filesystem in a subvolume makes it more flexible. I usually deploy flat layout to keep my home directory /home/<username> as an independent subvolume /@<username> and explicitly mount it via /etc/fstab. You may alternatively keep the whole /home as a subvolume.
The workaround described here may be useful trick to revert system by using non-@ subvolume as the root filesystem.
Use snapshot with btrfs
One of the greatest feature of btrfs is snapshot. There are a few interesting packages in Debian:
For maximum flexibility and simplicity, I am using my shell scripts bss .