Btrfs: Difference between revisions

From Alpine Linux
m (added wikilink)
 
(24 intermediate revisions by 10 users not shown)
Line 1: Line 1:
Documentation how to use Btrfs on Alpine Linux.
[https://wikipedia.org/wiki/Btrfs Btrfs] is a CoW (copy on write) filesystem with checksums, snapshots, compression and more.


== Install ==
== Installation ==


Installing [https://wikipedia.org/wiki/Btrfs Btrfs] is relatively straight forward. Install the package and tell Alpine to load the module on startup:
<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|apk add btrfs-progs
{{Cmd|<nowiki># export ROOTFS=btrfs</nowiki>}}
echo btrfs >> /etc/modules}}


To load the module right away, you can use the following command:
The filesystem utilities and modules will automatically be set up.


{{Cmd|modprobe btrfs}}
=== Manual Installation ===


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


To mount a volume on boot, add a new entry to your fstab:
{{Cmd|# apk add {{pkg|btrfs-progs}}
<nowiki># echo btrfs >> /etc/modules</nowiki>}}


UUID=abcdef-0055-4958-990f-1413ed1186ec  /var/data  btrfs  defaults,nofail,subvol=@  0  0
To load the module immediately, you can use the following command:


More information about mounting can be found in the official [https://btrfs.wiki.kernel.org/index.php/Main_Page Btrfs wiki]
{{Cmd|# modprobe btrfs}}


== Troubleshooting ==
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 ==
 
=== 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/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]
 
=== Enable btrfs-scan service ===
 
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}}
 
=== apk-snap  ===
 
The {{ic|apk-snap}} script from {{pkg|apk-snap}} package triggers filesystem snapshots before and after every apk commit.
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]].


=== Mount failed ===
This package autointalls {{pkg|snapper}} package and provides necessary apk hooks and script that causes {{ic|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.


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.
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 compress=zlib:3,subvol=@snaps_root 0 0</nowiki>}}


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:
=== Bootloader ===


#!/sbin/openrc-run
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.
name="btrfs-scan"
depend() {
  before localmount
}
start() {
  /sbin/btrfs device scan
}


Make the service executable and register it:
== Troubleshooting ==


{{Cmd|chmod +x /etc/init.d/btrfs-scan
=== Mount failed ===
rc-update add btrfs-scan boot
}}


The volume should mount correctly after a reboot.
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 [[#Enable btrfs-scan service|enable the btrfs-scan service]]. The volume should mount correctly after a reboot.


== Other Resources ==
== See also ==


# [https://garrit.xyz/posts/2021-12-31-btrfs-on-alpine BTRFS on Alpine Linux]
* [https://btrfs.readthedocs.io Btrfs documentation]
# [https://nparsons.uk/blog/using-btrfs-on-alpine-linux Using BTRFS on Alpine Linux]
* [https://garrit.xyz/posts/2021-12-31-btrfs-on-alpine BTRFS on Alpine Linux]
# [https://gitlab-test.alpinelinux.org/alpine/aports/-/issues/9539 Can't mount BTRFS volume using fstab]
* [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]]

Latest revision as of 17:53, 23 August 2025

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

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

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/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

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

... UUID=823a3283-30a7-4fef-b50b-8a2230c71b5b /.snapshots btrfs compress=zlib:3,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.

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.

See also

Retrieved from "https://wiki.alpinelinux.org/w/index.php?title=Btrfs&oldid=30774"