Using BTRFS on Alpine Linux

Alpine Linux is great, and its stripped-down, light-weight design is part of its appeal. However, that also means that sometimes things that "just work" on every other distro, present a few challenges on Alpine, and often need multiple steps to get them to work. BTRFS is one of those things, and its one that initially stopped me from using Alpine on my home server, but now I've found a solution and it's beautifully simple.


Install btrfs-progs

Firstly, you need to make sure that the btrfs kernel module is loaded on boot, and install btrfs-progs.

echo btrfs >> /etc/modules
apk add btrfs-progs

That's enough to let you be able to create and mount a new BTRFS device, but if you want to be able to mount an existing device (including after a reboot), you need to run btrfs device scan to scan all available devices for BTRFS signatures.

If you try to mount an existing partition before running btrfs device scan, you'll get the following error:

mount: <mount/point>: wrong fs type, bad option, bad superblock on <device>, missing codepage or helper program, or other error.

You could run that command manually after every reboot (or add it to your .bashrc or equivalent), but then BTRFS devices listed in /etc/fstab would fail to mount on boot. To get around that, you need to create a new service!

Create a new OpenRC service

Simply create a new service file at /etc/init.d/btrfs-scan with the following contents:

#!/sbin/openrc-run

name="btrfs-scan"

depend() {
  before localmount
}

start() {
  /sbin/btrfs device scan
}

Enable the service

Now you need to make the service file executable and enable the service for the boot runlevel.

chmod +x /etc/init.d/btrfs-scan
rc-update add btrfs-scan boot

Reboot

Finally, reboot! You should now be able to mount BTRFS partitions on boot.