Btrfs

2024-12-14T16:08:27Z

Adamthiede: service file is now in btrfs-progs package

Documentation how to use Btrfs on Alpine Linux.

== Install ==

Installing [https://wikipedia.org/wiki/Btrfs Btrfs] is relatively straight forward. Install the package and tell Alpine to load the module on startup:

{{Cmd|# apk add {{pkg|btrfs-progs}}
<nowiki># echo btrfs >> /etc/modules</nowiki>}}

To load the module immediately, you can use the following command:

{{Cmd|# modprobe btrfs}}

If using btrfs as your root filesystem, you should ensure that the initramfs is generated with the btrfs module, otherwise your system may fail to boot. To do so edit (as root) {{path|/etc/mkinitfs/mkinitfs.conf}} and ensure that "btrfs" is in the list of features; then (again as root) run the {{ic|mkinitfs}} command.

== Mounting a volume ==

To mount a volume on boot, add a new entry to your fstab:

{{cat|/etc/fstab|<nowiki>...
UUID=abcdef-0055-4958-990f-1413ed1186ec /var/data btrfs defaults,nofail,subvol=@ 0 0
</nowiki>}}

If you use more specific mounting options like for example:

{{cat|/etc/fstab|<nowiki>...
UUID=005f5994-f51c-4360-8c9b-589fa59ea6fc /mnt/hddext btrfs nofail,rw,noatime,commit=64,nossd,autodefrag,compress=zstd:10 0 2
</nowiki>}}

do not forget to install additional dependencies. If you enabled on the fly compression you need to install zstd:

{{cmd|# apk add {{pkg|zstd}}}}

More information about mounting can be found in the official [https://btrfs.readthedocs.io Btrfs wiki]

== Troubleshooting ==

=== Mount failed ===

If you try mounting a Btrfs volume via your {{path|/etc/fstab}} and it doesn't show up, it could be because Btrfs does not know about the drives during boot.

To work around this, you can enable the OpenRC service from the [https://gitlab.alpinelinux.org/alpine/aports/-/blob/master/main/btrfs-progs/btrfs-scan.initd btrfs-progs] package:

{{Cmd|<nowiki># rc-update add btrfs-scan boot
</nowiki>}}

The volume should mount correctly after a reboot.

== See also ==

* [https://garrit.xyz/posts/2021-12-31-btrfs-on-alpine BTRFS on Alpine Linux]
* [https://web.archive.org/web/20221127043947/https://nparsons.uk/blog/using-btrfs-on-alpine-linux Using BTRFS on Alpine Linux]
* [https://gitlab.alpinelinux.org/alpine/aports/-/issues/9539 Can't mount BTRFS volume using fstab]
* [https://wiki.archlinux.org/title/Btrfs ArchWiki]
* [https://wiki.gentoo.org/wiki/Btrfs Gentoo Wiki]
* [[Install Alpine on a btrfs filesystem with refind as boot manager]]
[[Category:Filesystems]]

Alpine Linux - User contributions [en]

Btrfs