Translation(s): English

FileSystem > Btrfs > Btrfs migration

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:

Dual boot preparation

Let's make a system dual bootable by installing a small secondary system onto an ext4 filesystem using debian-installer.

Migration of the root filesystem 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

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.

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 .