Btrfs

2026-01-15T21:59:56Z

Spider: /* Configuration */ Does the tip mean if you REuse a btrfs filesystem? I'm assuming yes since this is an article about using that filesystem.

[https://wikipedia.org/wiki/Btrfs Btrfs] is a CoW (copy on write) filesystem with checksums, snapshots, compression and more.

== Installation ==

The {{pkg|btrfs-progs}} package provides a number of user-space tools. To install the package:{{Cmd|# apk add {{pkg|btrfs-progs}}}}

When [[Installation|Installing Alpine linux]], <code>setup-disk</code> can automatically set up a root filesystem with Btrfs using [[Alpine_setup_scripts#Environment_Variables|environment variables]]. Export <code>ROOTFS</code> before running <code>setup-disk</code> or <code>setup-alpine</code> like so: {{Cmd|<nowiki># export ROOTFS=btrfs</nowiki>}}

The filesystem utilities and modules will automatically be set up.

=== Manual Installation ===

If btrfs is used for root filesystem, ensure that the initramfs is generated with the btrfs module, otherwise the system may fail to boot.

To do so edit the {{path|/etc/mkinitfs/mkinitfs.conf}} and ensure that "btrfs" is in the list of features as follows:{{Cat|/etc/mkinitfs/mkinitfs.conf|features{{=}}"ata base cdrom ext4 keymap kms mmc nvme raid scsi usb virtio btrfs"}}

After making the above change, issue the command to regenerate the initramfs:{{Cmd|# mkinitfs}}

== Configuration ==

To load the btrfs kernel module immediately, use the following command: {{Cmd|# modprobe btrfs}}

To mount non-root partitions with btrfs filesystem automatically on startup:{{Cmd|<nowiki># echo btrfs >> /etc/modules</nowiki>}}

Enabling {{ic|btrfs-scan}} service from the {{pkg|btrfs-progs}} package loads the btrfs kernel module and scans for and registers Btrfs devices with the kernel. To enable it: {{Cmd|# rc-update add btrfs-scan boot}}

{{Tip| Using {{ic|btrfs-scan}} service is recommended if btrfs file system is reused.}}

=== Mounting a subvolume ===

To mount a subvolume {{ic|@alpine}} located in the btrfs partition {{Path|/dev/nvme0n1p3}}, the command is: {{Cmd|<nowiki># mount -o subvol=@alpine /dev/nvme0n1p3 /mnt</nowiki>}}

=== Mounting a subvolume on boot ===

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 btrfs defaults,nofail,subvol=@var 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,autodefrag,compress=zstd:10 0 2</nowiki>}}

The option {{ic|defaults}} is recommended for most use cases. More information about mounting can be found in the official [https://btrfs.readthedocs.io Btrfs wiki]

=== apk-snap ===

The {{ic|apk-snap}} script from {{pkg|apk-snap}} package triggers filesystem snapshots before and after every apk commit using {{ic|snapper}} utility.

The {{pkg|apk-snap}} package is currently available in [[Repositories#Testing|testing]] repository. It can be safely installed by following the [[Repositories#Using_testing_repository|guidelines]].

The {ic|apk-snap}} script provides necessary apk hooks and script that causes {{ic|snapper}} utility to automatically take a pre and post snapshot before and after apk transactions, similar to how YaST does with OpenSuse. This provides a simple way to undo changes to a system after an apk transaction.

By default the '''/''' (root) snapshots taken by snapper are saved in the '''/.snapshot''' folder. To make it easier to manage the snapshots created by snapper, it is better to mainain it outside of '''/(root)''' folder. To achieve this, create a subvolume {{ic|@snaps_root}} in the btrfs partition and mount the above subvolume on '''/.snapshot''' folder by having an entry in {{Path|etc/fstab}} file as follows: {{Cat|/etc/fstab|<nowiki>...
UUID=823a3283-30a7-4fef-b50b-8a2230c71b5b /.snapshots btrfs defaults,subvol=@snaps_root 0 0</nowiki>}}

=== Bootloader ===

If the initrd and kernel are installed inside the btrfs root subvolume instead of EFI partition, configuring the bootloader properly is important. For sample configuration, refer to the following pages for [[Bootloaders#Manual_configuration|rEFInd]] and [[Immutable root with atomic upgrades#GRUB|GRUB]] bootloaders.

=== Btrbk ===

The backup tool [https://github.com/digint/btrbk btrbk] can be used to take backups using btrfs specific capabilities to create atomic snapshots and transfer them incrementally to your backup locations.

To install the package {{pkg|btrbk}}, issue the command:{{Cmd|# apk add {{pkg|btrbk}}}}

To use default [[BusyBox]], use the following global option in {{Path|/etc/btrbk/btrbk.conf}} as follows:{{Cat|/etc/btrbk/btrbk.conf|<nowiki>...
# activate the busybox compatibility
compat busybox
...</nowiki>}}

== Troubleshooting ==

=== Mount failed ===

If you try mounting a Btrfs volume via your {{path|/etc/fstab}} and if it doesn't show up, this is related to {{Issue|9539|Can't mount BTRFS volume using fstab}}. This could be because Btrfs does not know about the drives during boot. To avoid this issue [[#Configuration|enable the btrfs-scan]] service. The volume should mount correctly after a reboot.

=== Failed to fetch subvolume detail ===

In Alpine Linux, when running [[#Btrbk|btrbk]] with [[BusyBox]] defaults, you may encounter the above error 'Skipping subvolume "/mnt/btrfs/@myvolume": Failed to fetch subvolume detail'. To troubleshoot, run the command {{Cmd|# btrbk -n -l debug -L -S run}}

If you see the error {{Cmd|WARNING: ... sh: readlink -v -e '/mnt/btrfs/@myhome'
WARNING: ... readlink: unrecognized option: e}}

To resolve, either use the {{ic|compat busybox}} option as mentioned in [[#Btrbk|btrbk]] section or install the {{pkg|coreutils}} package.

== See also ==

* [https://btrfs.readthedocs.io Btrfs documentation]
* [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://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]]
* [[Immutable root with atomic upgrades|Immutable root with atomic upgrades using btrfs snapshots]]
[[Category:Filesystems]]

Alpine Linux - User contributions [en]

Btrfs