Btrfs: Difference between revisions

Revision as of 06:44, 2 April 2025

Documentation how to use Btrfs on Alpine Linux.

Installation

Installing Btrfs is relatively straight forward. Install the package and tell Alpine to load the module on startup:

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

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

# 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) /etc/mkinitfs/mkinitfs.conf and ensure that "btrfs" is in the list of features; then (again as root) run the mkinitfs command.

Configuration

Mounting a volume on boot

To mount a volume on boot, add a new entry to your /etc/fstab file as follows:

Contents of /etc/fstab

...
UUID=abcdef-0055-4958-990f-1413ed1186ec  /var/data  btrfs   defaults,nofail,subvol=@  0  0

If you use more specific mounting options like for example:

Contents of /etc/fstab

...
UUID=005f5994-f51c-4360-8c9b-589fa59ea6fc  /mnt/hddext  btrfs  nofail,rw,noatime,commit=64,nossd,autodefrag,compress=zstd:10  0 2

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

# apk add zstd

More information about mounting can be found in the official Btrfs wiki

Enable btrfs-scan service

To ensure that that btrfs partitions are cleanly mounted, enable the btrfs-scan service from the btrfs-progspackage:

# rc-update add btrfs-scan boot

Troubleshooting

Mount failed

If you try mounting a Btrfs volume via your /etc/fstab and it doesn't show up, it could be because Btrfs does not know about the drives during boot. To avoid this issue enable the btrfs-scan service. The volume should mount correctly after a reboot.

@@ Line 1: / Line 1: @@
-Documentation how to use BTRFS on Alpine Linux.
+Documentation how to use Btrfs on Alpine Linux.
-== Install ==
+== Installation ==
-Installing [https://de.wikipedia.org/wiki/Btrfs BTRFS] is relatively straight forward. Install the package and tell Alpine to load the module on startup:
+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 btrfs-progs
+{{Cmd|# apk add {{pkg|btrfs-progs}}
-echo btrfs >> /etc/modules}}
+<nowiki># echo btrfs >> /etc/modules</nowiki>}}
-To load the module right away, you can use the following command:
+To load the module immediately, you can use the following command:
-{{Cmd|modprobe btrfs}}
+{{Cmd|# modprobe btrfs}}
-== Mounting a volume ==
+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.
-To mount a volume on boot, add a new entry to your fstab:
+== Configuration ==
- UUID=abcdef-0055-4958-990f-1413ed1186ec  /var/data  btrfs   defaults,nofail,subvol=@  0  0
+=== Mounting a volume on boot ===
-More information about mounting can be found in the official [https://btrfs.wiki.kernel.org/index.php/Main_Page BTRFS wiki]
+To mount a volume on boot, add a new entry to your {{path|/etc/fstab}} file as follows: {{cat|/etc/fstab|<nowiki>...
+UUID=abcdef-0055-4958-990f-1413ed1186ec  /var/data  btrfs   defaults,nofail,subvol=@  0  0</nowiki>}}
-== Troubleshooting ==
+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>}}
-=== Mount failed ===
+Do not forget to install additional dependencies. If you enabled on the fly compression you need to install zstd: {{cmd|# apk add {{pkg|zstd}}}}
-If you try mounting a btrfs volume via your /etc/fstab and it doesn't show up, it could be because BTRFS does not know about the drives during boot.
+More information about mounting can be found in the official [https://btrfs.readthedocs.io Btrfs wiki]
-To work around this, you can create an OpenRC service that runs a ''btrfs scan'' to detect the drives. To do so, create a new service under /etc/init.d/btrfs-scan with the following content:
+=== Enable btrfs-scan service ===
- #!/sbin/openrc-run
+To ensure that that btrfs partitions are cleanly mounted, enable the {{ic|btrfs-scan}} service from the {{pkg|btrfs-progs}}package: {{Cmd|# rc-update add btrfs-scan boot}}
- name="btrfs-scan"
- depend() {
-   before localmount
- }
- start() {
-   /sbin/btrfs device scan
- }
-Make the service executable and register it:
+== Troubleshooting ==
+=== Mount failed ===
-{{Cmd|chmod +x /etc/init.d/btrfs-scan
+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 avoid this issue [[#Enable btrfs-scan service|enable the btrfs-scan service]]. The volume should mount correctly after a reboot.
-rc-update add btrfs-scan boot
-}}
-The volume should mount correctly after a reboot.
+== See also ==
-== Other Resources ==
+* [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]]
-# [https://garrit.xyz/posts/2021-12-31-btrfs-on-alpine BTRFS on Alpine Linux]
+[[Category:Filesystems]]
-# [https://nparsons.uk/blog/using-btrfs-on-alpine-linux Using BTRFS on Alpine Linux]
-# [https://gitlab-test.alpinelinux.org/alpine/aports/-/issues/9539 Can't mount BTRFS volume using fstab]