Btrfs
Btrfs is a CoW (copy on write) filesystem with checksums, snapshots, compression and more.
Installation
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
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 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
After making the above change, issue the command to regenerate the initramfs:
# mkinitfs
Configuration
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
If you use more specific mounting options like for example:
Contents of /etc/fstab
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
apk-snap
The apk-snap script from apk-snap package triggers filesystem snapshots before and after every apk commit.
The apk-snap package is currently available in testing repository. It can be safely installed by following the guidelines.
This package autointalls snapper package and provides necessary apk hooks and script that causes snapper 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
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.
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.