Btrfs - Revision history

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.

2026-01-15T21:59:56Z

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

← Older revision		Revision as of 21:59, 15 January 2026
Line 25:		Line 25:
	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}}		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 ~~used~~.}}		{{Tip\| Using {{ic\|btrfs-scan}} service is recommended if btrfs file system is reused.}}

	=== Mounting a subvolume ===		=== Mounting a subvolume ===

Prabuanand: added ... for clarity

2025-09-12T08:40:21Z

added ... for clarity

← Older revision		Revision as of 08:40, 12 September 2025
Line 64:		Line 64:
	To use default [[BusyBox]], use the following global option in {{Path\|/etc/btrbk/btrbk.conf}} as follows:{{Cat\|/etc/btrbk/btrbk.conf\|<nowiki>...		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		# activate the busybox compatibility
	compat busybox </nowiki>}}		compat busybox
			...</nowiki>}}

	== Troubleshooting ==		== Troubleshooting ==

Prabuanand: fixed wikilink

2025-09-12T08:37:13Z

fixed wikilink

← Older revision		Revision as of 08:37, 12 September 2025
Line 70:		Line 70:
	=== Mount failed ===		=== 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 [[#~~Enable btrfs-scan service~~\|enable the btrfs-scan ~~service~~]]. 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 [[#Configuration\|enable the btrfs-scan]] service. The volume should mount correctly after a reboot.

	=== Failed to fetch subvolume detail ===		=== Failed to fetch subvolume detail ===

Prabuanand: added Btrbk section with note on compat busybox option and relevant error message

2025-09-12T05:37:08Z

added Btrbk section with note on compat busybox option and relevant error message

@@ Line 55: / Line 55: @@
 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.
 == Troubleshooting ==
@@ Line 61: / Line 71: @@
 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.
 == See also ==

Prabuanand: reorganized page, removed inaccuracy related to zstd, nossd, added tip for btrfs-scan service

2025-09-12T04:59:34Z

reorganized page, removed inaccuracy related to zstd, nossd, added tip for btrfs-scan service

← Older revision		Revision as of 04:59, 12 September 2025
Line 3:		Line 3:
	== Installation ==		== Installation ==

	~~<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:~~		The {{pkg\|btrfs-progs}} package provides a number of user-space tools. To install the package:{{Cmd\|# apk add {{pkg\|btrfs-progs}}}}

	{{Cmd\|<nowiki># export ROOTFS=btrfs</nowiki>}}		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.		The filesystem utilities and modules will automatically be set up.
Line 11:		Line 11:
	=== Manual Installation ===		=== Manual Installation ===

	~~Installing Btrfs~~ is ~~relatively straight forward. Install~~ the ~~package and tell Alpine to load~~ the module ~~on startup:~~		If btrfs is used for root filesystem, ensure that the initramfs is generated with the btrfs module, otherwise the system may fail to boot.

	{{~~Cmd~~\|~~# apk add~~ {{~~pkg~~\|~~btrfs-progs}}~~		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"}}
	~~<nowiki># echo btrfs >>~~ /etc/~~modules<~~/~~nowiki>~~}}

	~~To load~~ the ~~module immediately~~, ~~you can use~~ the ~~following~~ command:		After making the above change, issue the command to regenerate the initramfs:{{Cmd\|# mkinitfs}}

	~~{{Cmd\|# modprobe btrfs}}~~		== Configuration ==

	~~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 load the btrfs kernel module immediately, use the following command: {{Cmd\|# modprobe btrfs}}

	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"~~}}		To mount non-root partitions with btrfs filesystem automatically on startup:{{Cmd\|<nowiki># echo btrfs >> /etc/modules</nowiki>}}

	~~After making~~ the ~~above change, issue~~ the ~~command to regenerate~~ the ~~initramfs~~:{{Cmd\|# ~~mkinitfs~~}}		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}}

	~~== Configuration ==~~		{{Tip\| Using {{ic\|btrfs-scan}} service is recommended if btrfs file system is used.}}

	=== Mounting a subvolume ===		=== Mounting a subvolume ===
Line 35:		Line 34:

	To mount a volume on boot, add a new entry to your {{path\|/etc/fstab}} file as follows: {{cat\|/etc/fstab\|<nowiki>...		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>}}		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>...		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>}}		UUID=005f5994-f51c-4360-8c9b-589fa59ea6fc /mnt/hddext btrfs nofail,rw,noatime,commit=64,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}}~~}}		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]

	~~More information about mounting can be found in the official [https://btrfs.readthedocs.io Btrfs wiki]~~		=== apk-snap ===

	=== ~~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~~}}		The {{ic\|apk-snap}} script from {{pkg\|apk-snap}} package triggers filesystem snapshots before and after every apk commit using {{ic\|snapper}} utility.

	~~=== 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]].
	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]].

	~~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.		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>...		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>}}		UUID=823a3283-30a7-4fef-b50b-8a2230c71b5b /.snapshots btrfs defaults,subvol=@snaps_root 0 0</nowiki>}}

	=== Bootloader ===		=== Bootloader ===

Prabuanand: added wikilink

2025-08-23T17:53:54Z

added wikilink

← Older revision		Revision as of 17:53, 23 August 2025
Line 2:		Line 2:

	== Installation ==		== Installation ==
	<code>setup-disk</code> can automatically set up a root filesystem with Btrfs using environment variables. Export <code>ROOTFS</code> before running <code>setup-disk</code> or <code>setup-alpine</code> like so:
			<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>}}		{{Cmd\|<nowiki># export ROOTFS=btrfs</nowiki>}}

TakodaOS: Adding a better introduction to Btrfs and easier instructions. Moving a link and adding another resource.

2025-08-23T15:34:20Z

Adding a better introduction to Btrfs and easier instructions. Moving a link and adding another resource.

← Older revision		Revision as of 15:34, 23 August 2025
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.

	== Installation ==		== Installation ==
			<code>setup-disk</code> can automatically set up a root filesystem with Btrfs using environment variables. Export <code>ROOTFS</code> before running <code>setup-disk</code> or <code>setup-alpine</code> like so:

	~~Installing [https:~~/~~/wikipedia~~.~~org/wiki/Btrfs~~ Btrfs] is relatively straight forward. Install the package and tell Alpine to load the module on startup:		{{Cmd\|<nowiki># export ROOTFS=btrfs</nowiki>}}

			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:

	{{Cmd\|# apk add {{pkg\|btrfs-progs}}		{{Cmd\|# apk add {{pkg\|btrfs-progs}}
Line 62:		Line 69:
	== See also ==		== See also ==

			* [https://btrfs.readthedocs.io Btrfs documentation]
	* [https://garrit.xyz/posts/2021-12-31-btrfs-on-alpine BTRFS on Alpine Linux]		* [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://web.archive.org/web/20221127043947/https://nparsons.uk/blog/using-btrfs-on-alpine-linux Using BTRFS on Alpine Linux]

Prabuanand: added link for grub

2025-06-13T16:13:16Z

added link for grub

← Older revision		Revision as of 16:13, 13 June 2025
Line 50:		Line 50:
	UUID=823a3283-30a7-4fef-b50b-8a2230c71b5b /.snapshots btrfs compress=zlib:3,subvol=@snaps_root 0 0</nowiki>}}		UUID=823a3283-30a7-4fef-b50b-8a2230c71b5b /.snapshots btrfs compress=zlib:3,subvol=@snaps_root 0 0</nowiki>}}

	=== Bootloader===		=== Bootloader ===

	If the initrd and kernel are installed inside the btrfs root subvolume instead of EFI partition, configuring the bootloader properly is important. ~~Refer~~ to the ~~sample configuration~~ for [[Bootloaders#Manual_configuration\|rEFInd ~~bootloader~~]] ~~for such an use case~~.		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.

	== Troubleshooting ==		== Troubleshooting ==

Prabuanand: added Bootloader section and added wikilinks

2025-06-13T16:00:07Z

added Bootloader section and added wikilinks

← Older revision		Revision as of 16:00, 13 June 2025
Line 49:		Line 49:
	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>...		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>}}		UUID=823a3283-30a7-4fef-b50b-8a2230c71b5b /.snapshots btrfs compress=zlib:3,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. Refer to the sample configuration for [[Bootloaders#Manual_configuration\|rEFInd bootloader]] for such an use case.

	== Troubleshooting ==		== Troubleshooting ==
Line 63:		Line 67:
	* [https://wiki.gentoo.org/wiki/Btrfs Gentoo Wiki]		* [https://wiki.gentoo.org/wiki/Btrfs Gentoo Wiki]
	* [[Install Alpine on a btrfs filesystem with refind as boot manager]]		* [[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]]		[[Category:Filesystems]]

Prabuanand: added mount command, apk-snap, changed heading,rephrased sentence

2025-04-03T11:27:39Z

added mount command, apk-snap, changed heading,rephrased sentence

← Older revision		Revision as of 11:27, 3 April 2025
Line 12:		Line 12:
	{{Cmd\|# modprobe btrfs}}		{{Cmd\|# 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)~~ {{path\|/etc/mkinitfs/mkinitfs.conf}} and ensure that "btrfs" is in the list of features~~; then (again~~ as ~~root) run~~ the {{ic\|mkinitfs}} ~~command.~~		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 ==		== Configuration ==

	=== Mounting a ~~volume~~ on boot ===		=== 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>...		To mount a volume on boot, add a new entry to your {{path\|/etc/fstab}} file as follows: {{cat\|/etc/fstab\|<nowiki>...
Line 31:		Line 39:

	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}}		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]].

			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.

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

	== Troubleshooting ==		== Troubleshooting ==
Line 36:		Line 54:
	=== Mount failed ===		=== Mount failed ===

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

	== See also ==		== See also ==
Line 42:		Line 60:
	* [https://garrit.xyz/posts/2021-12-31-btrfs-on-alpine BTRFS on Alpine Linux]		* [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://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.archlinux.org/title/Btrfs ArchWiki]
	* [https://wiki.gentoo.org/wiki/Btrfs Gentoo Wiki]		* [https://wiki.gentoo.org/wiki/Btrfs Gentoo Wiki]