Btrfs

This is a procedure to convert a root filesystem into btrfs for a server, either on a Gandi VM or a Scaleway machine.

This was written after a number of trial-error. Here are my steps if it can be useful to others. For an introduction, see Wikipedia article and/or the dedicated wiki.

WARNING: this could cause DATA LOSS, be sure you have backups (possibly Gandi snapshots).

General strategies

Often the VM are formatted in ext4 by default without option to easily use another filesystem. To hackily change this, there are 2 different strategies:

1. Use another system, with two variations:
   1. detach the root filesystem and attach it to another machine, convert it, and re-attach it to the original machine,
   2. use a secondary system to convert the filesystem with btrfs-convert, when it is not possible to detach the root filesystem (e.g. OpenStack),
2. Mount a minimal root filesystem in RAM, pivot the root to this filesystem, unmount the on-disk filesystem, use btrfs-convert on the on-disk filesystem, pivot back.

On any server

General idea: mount the root filesystem in RAM, pivot the root, then unmount the on-disk filesystem, and convert it to btrfs.

Source: This is mainly based on this StackOverflow + tool btrfs-convert.

Context (OS): It is assumed Debian 11 or 12 here, it works probably similarly on others distros with small adaptations.

Context (size of RAM): It is assumed a small system, else you have to sort what you need in the RAM fs during the command `cp -az . tmproot`.

Context (time required): Expect a few dozen of minutes for this procedure if everything works fine and you have a small (<5 GiB) root fs, else expect some hours for a large root fs or in case of issues.

WARNING: this can make the server failing hard or even be lost in case of failure, be sure ALL YOUR DATA are saved elsewhere!

Gandi CloudV5 + Debian 11

This variant was tested on Gandi CloudV5 on Debian 11 on 2025-02-15.

As root:

1. apt-get update
2. apt-get upgrade
3. apt-get install btrfs-progs psmisc
4. apt-get autoremove --purge
5. apt-get clean
6. reboot
7. umount -a
8. cd /
9. mkdir tmproot
10. df -hT /
11. mount -t tmpfs tmpfs -o size=2G tmproot # adapt to the size of root fs
12. cp -ax . tmproot # if the root fs is larger than the RAM, you have to choose what to copy here, see the StackOverflow link above
13. mkdir tmproot/oldroot
14. mount --make-rprivate /
15. pivot_root tmproot tmproot/oldroot
16. for i in dev proc sys run; do mount --move /oldroot/$i /$i; done
17. systemctl restart systemd-timesyncd.service systemd-udevd.service systemd-logind.service systemd-journald.service acpid.service dbus.service ssh.service rsyslog.service cron.service
18. systemctl daemon-reexec
19. (open a second SSH connection to check it works)
20. (stop all SSH connections, wait 10-15 seconds, then reconnect with SSH) (`systemctl --user` is stopped 10 seconds after the last SSH connection is closed)
21. umount /oldroot
22. (if it is still busy, check with `fuser -vm /oldroot` the services still using /oldroot, stop/restart these services)
23. rmdir /oldroot
24. blkid # to identify the on-disk root fs, let’s say /dev/xvda1
25. btrfs-convert -p /dev/xvda1
26. mount /dev/xvda1 /mnt
27. btrfs subvolume delete -C /mnt/ext2_saved
28. btrfs filesystem defragment -r /mnt # optional; quick if small fs (<5 GiB), may be long else
29. btrfs balance start --full-balance /mnt # optional; quick if small fs (<5 GiB), may be long else
30. umount /mnt
31. mkdir /oldroot
32. mount /dev/xvda1 /oldroot
33. mount --make-rprivate /
34. pivot_root /oldroot /oldroot/tmproot
35. for i in dev proc sys run; do mount --move /tmproot/$i /$i; done
36. systemctl restart systemd-timesyncd.service systemd-udevd.service systemd-logind.service systemd-journald.service acpid.service dbus.service ssh.service rsyslog.service cron.service
37. systemctl daemon-reexec
38. (open a second SSH connection to check it works)
39. (stop all SSH connections, wait 10-15 seconds, then reconnect with SSH) (`systemctl --user` is stopped 10 seconds after the last SSH connection is closed)
40. umount /tmproot
41. (if it is still busy, check with `fuser -vm /tmproot` the services still using /tmproot, stop/restart these services)
42. rmdir /tmproot
43. blkid # copy the UUID of the on-disk root fs
44. vi /etc/fstab # change the root fs with: UUID=<new_value> / btrfs defaults 0 1
45. update-grub
46. (possibly grub-install)

Ikoula VPS + Debian 12

This variant was tested on Ikoula VPS on Debian 12 on 2025-02-17.

As root:

1. apt-get update
2. apt-get upgrade
3. apt-get install btrfs-progs psmisc
4. apt-get autoremove --purge
5. apt-get clean
6. reboot
7. umount -a
8. cd /
9. mkdir tmproot
10. df -hT /
11. mount -t tmpfs tmpfs -o size=2G tmproot # adapt to the size of root fs
12. cp -ax . tmproot # if the root fs is larger than the RAM, you have to choose what to copy here, see the StackOverflow link above
13. mkdir tmproot/oldroot
14. mount --make-rprivate /
15. pivot_root tmproot tmproot/oldroot
16. for i in dev proc sys run; do mount --move /oldroot/$i /$i; done
17. systemctl restart systemd-timesyncd.service systemd-udevd.service systemd-logind.service systemd-journald.service qemu-guest-agent.service serial-getty@ttyS0.service getty@tty1.service dbus.service
18. systemctl restart systemd-networkd.service
19. systemctl restart ssh.service
20. systemctl daemon-reexec
21. (open a second SSH connection to check it works)
22. (stop all SSH connections, wait 10-15 seconds, then reconnect with SSH) (`systemctl --user` is stopped 10 seconds after the last SSH connection is closed)
23. umount /oldroot
24. (if it is still busy, check with `fuser -vm /oldroot` the services still using /oldroot, stop/restart these services)
25. rmdir /oldroot
26. blkid # to identify the on-disk root fs, let’s say /dev/sda1
27. btrfs-convert -p /dev/sda1
28. mount /dev/sda1 /mnt
29. btrfs subvolume delete -C /mnt/ext2_saved
30. btrfs filesystem defragment -r /mnt # optional; quick if small fs (<5 GiB), may be long else
31. btrfs balance start --full-balance /mnt # optional; quick if small fs (<5 GiB), may be long else
32. umount /mnt
33. mkdir /oldroot
34. mount /dev/sda1 /oldroot
35. mount --make-rprivate /
36. pivot_root /oldroot /oldroot/tmproot
37. for i in dev proc sys run; do mount --move /tmproot/$i /$i; done
38. systemctl restart systemd-timesyncd.service systemd-udevd.service systemd-logind.service systemd-journald.service qemu-guest-agent.service serial-getty@ttyS0.service getty@tty1.service dbus.service
39. systemctl restart systemd-networkd.service
40. systemctl restart ssh.service
41. systemctl daemon-reexec
42. (open a second SSH connection to check it works)
43. (stop all SSH connections, wait 10-15 seconds, then reconnect with SSH) (`systemctl --user` is stopped 10 seconds after the last SSH connection is closed)
44. umount /tmproot
45. (if it is still busy, check with `fuser -vm /tmproot` the services still using /tmproot, stop/restart these services)
46. rmdir /tmproot
47. blkid # copy the UUID of the on-disk root fs
48. vi /etc/fstab # change the root fs with: UUID=<new_value> / btrfs defaults 0 1
49. (I found also occurrences of the old ext4 UUID in /boot/efi/EFI/debian/grub.cfg and /boot/grub/x86_64-efi/load.cfg in the parameter search.fs_uuid, I changed these to the new btrfs UUID)
50. update-grub
51. reboot

GandiCloudVPS

Tested on Debian 12 on 2024-10-08.

GandiCloudVPS is powered by OpenStack, and it is not possible (according to my understanding) to detach the root filesystem, so it is not possible to mount another volume converted to btrfs (although a new server may be created with an existing volume with openstack server create --volume UUID …).

1. Restart the VM in rescue mode
2. Connect by SSH or with the remote console in this rescue mode
3. Identify the filesystems on the server in rescue mode with blkid and/or df -hT, for instance
   • /dev/xvdb1 for the root filesystem /
   • /dev/xvdb15 for /boot/efi
4. apt-get update && apt-get install -y btrfs-progs
5. btrfs-convert -p /dev/xvdb1
6. mount /dev/xvdb1 /mnt
7. btrfs subvolume delete -C /mnt/ext2_saved
8. btrfs filesystem defragment -r /mnt
9. btrfs balance start /mnt
10. blkid and note the UUID of the btrfs filesystem
11. cp /mnt/etc/fstab /tmp (to temporarily keep a backup if needed)
12. Edit /mnt/etc/fstab, replace the UUID of the root filesystem by the new UUID, replace the type "ext4" by "btrfs", and replace the options by "defaults"
13. for i in dev dev/pts proc sys; do mount --bind /$i /mnt/$i; done
14. mount /dev/xvdb15 /mnt/boot/efi
15. chroot /mnt update-grub
16. chroot /mnt grub-install /dev/xvdb
17. for i in dev/pts dev proc sys boot/efi boot ""; do umount /mnt/$i; done
18. Restart in normal mode
19. Verify that everything works with df -hT
20. If the server does not restart, it may be observed why on the remote console. Then restart in rescue mode, remount the new filesystem on /mnt and check:
    1. that /mnt/etc/fstab has the right UUID, type "btrfs", options "defaults"

Gandi CloudV5

This was updated on 2020-09-24 for Debian 10 buster + GandiV5, and on 2022-02-02 for Debian 11 bullseye + GandiV5. An older version was for Debian 9 jessie or Ubuntu 18.04 LTS + GandiV4.

Manual procedure

Create the server

On GandiV5, create a new server with e.g. 1 proc, 256 MiB RAM, 1 system disk of 5 GiB, Debian 10 buster or Debian 11 bullseye.

For Debian 10 buster (only), define backports (btrfs-progs must contain btrfs-convert, see this Debian bug) (this is not needed for Debian 11):

echo 'deb https://deb.debian.org/debian buster-backports main' > /etc/apt/sources.list.d/debian-backports.list

Install btrfs-progs:

apt update && apt install -t buster-backports btrfs-progs # Debian 10 buster
apt update && apt install btrfs-progs # Debian 11 bullseye

On GandiV5 :

1. stop the server,
2. open the page about the system disk in Volumes,
3. clone the system disk with another (definitive) name (e.g. the current disk is "sys-myserver", you can define the copied disk as "myserver"),
4. start the server,
5. wait until the server is started,
6. attach this cloned disk to the server.

ATTENTION: really start the server before attaching the cloned disk, else the root filesystem might be the cloned disk given they have the same UUID and /etc/fstab is using the UUID to select the root filesystem (it could be workarounded by setting /dev/xvda1 in /etc/fstab before stopin the server).

Convert to btrfs

Mostly from [1]

Display the active root filesystem, and you will be able to deduce what is the cloned filesystem:

ls /dev/xvd*
mount|grep xvd
blkid

Copy the result of blkid in some text file on your computer (will be used later).

Let’s say /dev/xvdb1 is the clone filesystem, we convert it to btrfs: (man 8 btrfs-convert)

fsck.ext4 -f /dev/xvdb1 # optional
btrfs-convert -p /dev/xvdb1

Here, I obtained the following error:

root@test:~# btrfs-convert -p /dev/xvdb1
create btrfs filesystem:
	blocksize: 4096
	nodesize:  16384
	features:  extref, skinny-metadata (default)
creating ext2 image file
creating btrfs metadata
Unable to find block group for 0 27081]
Unable to find block group for 0
Unable to find block group for 0
ctree.c:2245: split_leaf: BUG_ON `1` triggered, value 1
btrfs-convert(+0x11b5a)[0x559c159c1b5a]
btrfs-convert(+0x1589b)[0x559c159c589b]
btrfs-convert(btrfs_search_slot+0x269)[0x559c159c6401]
btrfs-convert(btrfs_insert_empty_items+0x92)[0x559c159c7b3c]
btrfs-convert(btrfs_record_file_extent+0x1bc)[0x559c159d46b4]
btrfs-convert(record_file_blocks+0x14a)[0x559c159bfe92]
btrfs-convert(+0x10349)[0x559c159c0349]
btrfs-convert(+0x1135f)[0x559c159c135f]
btrfs-convert(main+0x1f59)[0x559c159bdefb]
/lib/x86_64-linux-gnu/libc.so.6(__libc_start_main+0xe7)[0x7f4c11c3bb97]
btrfs-convert(_start+0x2a)[0x559c159bb5ca]
Aborted

According to [2] and [3], it can be worked around: (this command could take some hours, depending on disk size and number of files)

btrfs-convert -d -p /dev/xvdb1

or even:

btrfs-convert -n -d -p /dev/xvdb1

Or, if still unsuccessful, try to add free space, or if still unsuccessfull, re-compile btrfs-progs in version 4.17.1 (this last try worked for me for 50 Gio disk with 24 Gio free space on Debian 9 jessie, expanded after its original size was 30 Gio (=4 Gio free space)).

Then, mount the filesystem and delete the old ext4 snapshot:

mount /dev/xvdb1 /mnt
btrfs subvolume delete /mnt/ext2_saved
btrfs filesystem defrag -r /mnt # could take dozen of minuts
btrfs balance start /mnt # could take hours

Promote as root filesystem

Mostly from [4]

Edit the /etc/fstab of the btrfs system:

uuid=`blkid|grep -P '^/dev/xvdb1: '|grep -o -P ' UUID="[0-9a-f-]+" '|cut -d'"' -f2`
sed -i -E 's/^UUID=[0-9a-f-]+ *\/ .*$/UUID=$uid \/               btrfs    defaults 0       1/' /mnt/etc/fstab

Update Grub in a chrooted system:

for i in dev dev/pts proc sys; do mount --bind /$i /mnt/$i; done
chroot /mnt update-grub
for i in dev/pts dev proc sys; do umount /mnt/$i; done
umount /mnt

Quit:

exit

Define the cooked disk as boot disk

In Gandi V5 interface, stop the server, detach the old root disk and define the cooked disk as "Use to start".

Launch the server (it should correctly start, even if the /boot directory is on the main partition / (some old documents said it didn’t work because grub didn’t know the btrfs filesystem, but it is fixed now)).

df -hT

It should show something like:

/dev/xvda1     btrfs      50G   32G   19G  63% /

Delete the old root disk.

You can delete the packages grub-efi-amd64, grub-efi-amd64-bin, grub-pc, grub-pc-bin since they are not used, but keep /etc/default/grub with Gandi customisations:

cp -a /etc/default/grub /root/grub
apt-get purge -y grub-efi-amd64 grub-efi-amd64-bin grub-pc grub-pc-bin
mv /root/grub /etc/default/grub
apt-mark manual grub-common grub2-common
update-grub # to check it still work and you should reboot now to be sure it reboots correctly

Scripted procedure

This script automates the conversion, with a slightly-modified procedure.

On GandiV5, create a new server with e.g. 1 proc, 256 MiB RAM, 1 system disk of 5 GiB, Debian 11 bullseye.

On GandiV5 :

1. stop the server,
2. open the page about the system disk in Volumes,
3. clone the system disk with another (definitive) name (e.g. the current disk is "sys-myserver", you can define the copied disk as "myserver"),
4. start the server,
5. wait until the server is started,
6. attach this cloned disk to the server.

ATTENTION: really start the server before attaching the cloned disk, else the root filesystem might be the cloned disk given they have the same UUID and /etc/fstab is using the UUID to select the root filesystem (it could be workarounded by setting /dev/xvda1 in /etc/fstab before stopin the server).

1. Launch this script as root: (vi convert_gandiroot_to_btrfs.sh + chmod +x convert_gandiroot_to_btrfs.sh + (./convert_gandiroot_to_btrfs.sh)

   The script takes about 3 minutes to convert a 1.4 GiB disk.

#!/bin/sh

set -e

fs_type=`mount|grep -F ' on / '|grep -o -E ' type [a-z0-9]+ '|cut -d' ' -f3`
blkid=`blkid|grep -F ' LABEL="gandiroot" '`
nb_fs_gandiroot=`echo "$blkid"|cut -d: -f2-|uniq -c|tr -s ' '|cut -d' ' -f2`
if [ "$fs_type" != 'ext4' -o ! "$nb_fs_gandiroot" = 2 ]; then
    echo 'It is not possible to convert the disk. There should be two identical devices labeled "gandiroot" formatted in ext4'
    exit 2
fi
fs_gandiroot_ext4=`echo "$blkid"|head -n1|cut -d: -f1`
fs_gandiroot_btrfs=`echo "$blkid"|tail -n1|cut -d: -f1`

echo
echo "Current root filesystem: $fs_gandiroot_ext4 (ext4)"
echo "Future root filesystem: $fs_gandiroot_btrfs (currently ext4, will be btrfs)"

set -v

apt-get update

apt-get install -y btrfs-progs

fsck.ext4 -f "$fs_gandiroot_btrfs"

btrfs-convert -p "$fs_gandiroot_btrfs"

mount "$fs_gandiroot_btrfs" /mnt

btrfs subvolume delete -C /mnt/ext2_saved

btrfs filesystem defragment -r /mnt

btrfs balance start /mnt

new_uuid=`blkid|grep -P "^$fs_gandiroot_btrfs: "|grep -o -P ' UUID="[0-9a-f-]+" '|cut -d'"' -f2`

sed -i -E "s/^UUID=[0-9a-f-]+ *\/ .*$/UUID=$new_uuid \/               btrfs    defaults 0       1/" /mnt/etc/fstab

for i in dev dev/pts proc sys; do mount --bind /$i /mnt/$i; done

chroot /mnt update-grub

for i in dev/pts dev proc sys; do umount /mnt/$i; done

umount /mnt

In Gandi V5 interface, stop the server, detach the old root disk and define the cooked disk as "Use to start".

Launch the server and execute:

df -hT

It should show something like:

/dev/xvda1     btrfs      5G   1.4G   3.5G  28% /

Delete the old root disk.

Scaleway Elastic Metal

Tested on Debian 11.

1. On the running server, find the name of the partitions with blkid for the root filesystem / and /boot and /boot/efi
2. Restart in rescue mode
3. Identify the filesystems on the server in rescue mode with blkid and/or df -hT, for instance
   • /dev/md126 for the root filesystem /
   • /dev/md127 for /boot
   • /dev/sda1 for /boot/efi
4. apt-get update && apt-get install -y btrfs-progs
5. btrfs-convert -p /dev/md126
6. mount /dev/md126 /mnt
7. btrfs subvolume delete -C /mnt/ext2_saved
8. btrfs filesystem defragment -r /mnt
9. btrfs balance start /mnt
10. blkid and note the UUID of the btrfs filesystem
11. cp /mnt/etc/fstab /tmp (to temporarily keep a backup if needed)
12. Edit /mnt/etc/fstab, replace the UUID of the root filesystem by the new UUID, replace the type "ext4" by "btrfs", and replace the options by "defaults"
13. for i in dev dev/pts proc sys; do mount --bind /$i /mnt/$i; done
14. mount /dev/md127 /mnt/boot
15. mount /dev/sda1 /mnt/boot/efi
16. chroot /mnt update-grub
17. for i in dev/pts dev proc sys boot/efi boot ""; do umount /mnt/$i; done
18. Restart in normal mode
19. Verify that everything works with df -hT
20. If the server does not restart, restart in rescue mode, remount the new filesystem on /mnt and check:
    1. that /mnt/etc/fstab has the right UUID, type "btrfs", options "defaults"
    2. perhaps chroot /mnt grub-install /dev/md126 or something like that may be needed, after the six filesystems /mnt/dev… were mounted

Troubleshootings

• During a conversion, the root filesystem was mounted read-only in btrfs; it was probably because I didn’t change the options "rw,noatime,errors=remount-ro" to "defaults"

External links

• PvGrub2 on Xen wiki