Btrfs

Btrfs is a CoW (copy on write) filesystem with checksums, snapshots, compression and more.

Installation

The btrfs-progs package provides a number of user-space tools. To install the package:

# apk add btrfs-progs

When Installing Alpine linux, setup-disk can automatically set up a root filesystem with Btrfs using environment variables. Export ROOTFS before running setup-disk or setup-alpine like so:

# export ROOTFS=btrfs

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 /etc/mkinitfs/mkinitfs.conf and ensure that "btrfs" is in the list of features as follows:

Contents of /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:

# mkinitfs

Configuration

To load the btrfs kernel module immediately, use the following command:

# modprobe btrfs

To mount non-root partitions with btrfs filesystem automatically on startup:

# echo btrfs >> /etc/modules

Enabling btrfs-scan service from the btrfs-progs package loads the btrfs kernel module and scans for and registers Btrfs devices with the kernel. To enable it:

# rc-update add btrfs-scan boot

Tip: Using btrfs-scan service is recommended if btrfs file system is used.

Mounting a subvolume

To mount a subvolume @alpine located in the btrfs partition /dev/nvme0n1p3, the command is:

# mount -o subvol=@alpine /dev/nvme0n1p3 /mnt

Mounting a subvolume 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 btrfs defaults,nofail,subvol=@var 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,autodefrag,compress=zstd:10 0 2

The option defaults is recommended for most use cases. More information about mounting can be found in the official Btrfs wiki

apk-snap

The apk-snap script from apk-snap package triggers filesystem snapshots before and after every apk commit using snapper utility.

The apk-snap package is currently available in testing repository. It can be safely installed by following the guidelines.

The {ic|apk-snap}} script provides necessary apk hooks and script that causes 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 @snaps_root in the btrfs partition and mount the above subvolume on /.snapshot folder by having an entry in etc/fstab file as follows:

Contents of /etc/fstab

... UUID=823a3283-30a7-4fef-b50b-8a2230c71b5b /.snapshots btrfs defaults,subvol=@snaps_root 0 0

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 rEFInd and GRUB bootloaders.

Btrbk

The backup tool 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 btrbk, issue the command:

# apk add btrbk

To use default BusyBox, use the following global option in /etc/btrbk/btrbk.conf as follows:

Contents of /etc/btrbk/btrbk.conf

... # activate the busybox compatibility compat busybox ...

Troubleshooting

Mount failed

If you try mounting a Btrfs volume via your /etc/fstab and if it doesn't show up, this is related to #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 enable the btrfs-scan service. The volume should mount correctly after a reboot.

Failed to fetch subvolume detail

In Alpine Linux, when running 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

# btrbk -n -l debug -L -S run

If you see the error

WARNING: ... sh: readlink -v -e '/mnt/btrfs/@myhome' WARNING: ... readlink: unrecognized option: e

To resolve, either use the compat busybox option as mentioned in btrbk section or install the coreutils package.

See also

• Btrfs documentation
• BTRFS on Alpine Linux
• Using BTRFS on Alpine Linux
• ArchWiki
• Gentoo Wiki
• Install Alpine on a btrfs filesystem with refind as boot manager
• Immutable root with atomic upgrades using btrfs snapshots