[SOLVED] Confused about how to use Btrfs on Arch Linux

richard-rumpel · 2025-10-29 13:29:27

Hello, I've been using Arch Linux for a while, and for the installation on a new system, I wanted to take a closer look at Btrfs, as I find the snapshot functionality very interesting. Therefore, I've first done some practice to familiarize myself with the tools for this filesystem. So far, I was following this guide to install Arch Linux: [https://gist.github.com/mjkstra/96ce7a5 … k-mounting](https://gist.github.com/mjkstra/96ce7a5 … k-mounting)

I'm a bit confused right now, as some things I read in the documentation didn’t match my expectations. Below, I’ve outlined what I mean:

I - This is my starting point

(1)# dd if=/dev/zero bs=1024k count=1000 of=/tmp/test.img
(2)# losetup -f /tmp/test-btrfs.img
(3)# mkfs.btrfs /dev/loop0
(4)# mount /dev/loop0 /mnt

(5)#  mount | grep /mnt
/dev/loop0 on /mnt type btrfs (rw,relatime,ssd,space_cache=v2,subvolid=5,subvol=/)

(6)# btrfs subvol list /mnt

so far nothing unexpected for me ...

II – Create Subvolume

(7)# btrfs subvol create /mnt/@test1
Create subvolume '/mnt/@test1'

(8)# btrfs subvol list /mnt/
ID 264 gen 23 top level 5 path @test1

(9)# ls -al /mnt/
insgesamt 20
drwxr-xr-x  1 root root   12 29. Okt 10:13 .
drwxr-xr-x 20 root root 4096 19. Mai 12:39 ..
drwxr-xr-x  1 root root    0 29. Okt 10:13 @test1

(10)# rmdir /mnt/\@test1/
(11)# ls -al /mnt/
insgesamt 20
drwxr-xr-x  1 root root    0 29. Okt 10:32 .
drwxr-xr-x 20 root root 4096 19. Mai 12:39 ..

(12)# btrfs subvol list /mnt/

It was unexpected for me that (8) also created a folder with the name of the new subvolume, as you can see in (9) but okay ...
When I delete this new folder (10) the subvolume also gets deleted (10) - what ? Why?

I know that Btrfs subvolumes have to be explicitly mounted with a command like "mount -o subvol=@test1 /dev/loop0 /mnt/<some mount point>"

III – Create Subvolume and Mount It to Another Place

(13)# mkdir /mnt/test2_

(14)# btrfs subvol create /mnt/@test2
Create subvolume '/mnt/@test2'

(15)# mount -o subvol=@test2 /dev/loop0 /mnt/test2_

(16)# date > /mnt/test2_/date1.txt ; date > /mnt/@test2/date2.txt

(17)# ls -al /mnt/*
/mnt/@test2:
insgesamt 24
drwxr-xr-x 1 root root 36 29. Okt 10:45 .
drwxr-xr-x 1 root root 24 29. Okt 10:44 ..
-rw-r--r-- 1 root root 29 29. Okt 10:45 date1.txt
-rw-r--r-- 1 root root 29 29. Okt 10:45 date2.txt

/mnt/test2_:
insgesamt 24
drwxr-xr-x 1 root root 36 29. Okt 10:45 .
drwxr-xr-x 1 root root 24 29. Okt 10:44 ..
-rw-r--r-- 1 root root 29 29. Okt 10:45 date1.txt
-rw-r--r-- 1 root root 29 29. Okt 10:45 date2.txt


(18)# rm -rf /mnt/\@test2

(19)# ls -al
insgesamt 20
drwxr-xr-x  1 root root   12 29. Okt 10:56 .
drwxr-xr-x 20 root root 4096 19. Mai 12:39 ..
drwxr-xr-x  1 root root    0 29. Okt 10:56 test2_

(20)# ls -al test2_
insgesamt 0

(21)# btrfs subvol list /mnt/

So after deleting the folder (18), the files in the mounted folder are also gone. This was also something that I didn’t expect.
It seems to me that the mount on "/mnt/test2_" works more like a bind mount.

After all, it seems to be necessary anymore to explicitly mount the subvolume (and add them to fstab as well). You have to think of a subvolume like a directory, but instead of using mkdir, you use Btrfs tools to create it.
Is there something that I’m missing here?

Also, I'd like to know if I want to do a disk copy-on-write for a subvolume, the only currently possible way is to use "chattr +C /mnt/vm-disk-images"?

I hope it’s clear what the problem in my mind is and that somebody could make it clearer how to handle Btrfs subvolumes.

ls -al /mnt
drwxr-xr-x  1 root root   18 29. Okt 14:35 @test6
drwxr-xr-x  1 root root   18 29. Okt 14:33 @test6_snap1
drwxr-xr-x  1 root root   18 29. Okt 14:33 @test6_snap1_r
drwxr-xr-x  1 root root   18 29. Okt 14:35 @test6_snap2
drwxr-xr-x  1 root root   18 29. Okt 14:35 @test6_snap2_r

Also, I'd like to mention that when I create a snapshot, it is directly visible as new folder. Is that really the intended behavior?

Thanks a lot.
Richard

Last edited by richard-rumpel (2025-11-10 18:57:20)

V1del · 2025-10-29 15:15:27

What do/did you expect to happen instead? All of the things you list so far very much match with my expectation, but you didn't really elaborate on what you expected to happen instead of what is actually happening.

Also general disclaimer, third party guides are discouraged, does https://wiki.archlinux.org/title/Btrfs#Subvolumes help clear things up?

richard-rumpel · 2025-10-31 16:32:03

Hey V1del, thanks a lot for your reply. You’re right — the behavior is exactly as described in the wiki.

What surprised me was that “btrfs subvol create” and “btrfs subvolume create” directly create a folder in the filesystem and kind of "mount the subvolume".

What really helped me understand the whole thing was the sentence: "A Btrfs subvolume is not a block device (and cannot be treated as one) instead, a Btrfs subvolume can be thought of as a POSIX file namespace. This namespace can be accessed via the top-level subvolume of the file system, or it can be mounted in its own right."

I had also set up a virtual machine using the Archinstall script, where I chose the recommended default Btrfs layout, and I didn’t observe this behavior there. I don’t want to have a separate folder with the snapshot’s name in the filesystem for every snapshot I create.

In the meantime, I’ve realized why this happens.

The installer creates the filesystem and places the root of the filesystem directly inside a subvolume. The actual root of the filesystem isn’t mounted at all.

This is what it looks like after a fresh installation:

# cat /etc/fstab 
...
# /dev/vda2
UUID=<uid of partion> / btrfs rw,relatime,nodatasum,nodatacow,discard=async,space_cache=v2,subvol=/@ 0 0

# /dev/vda2
UUID=<uid of partion> /home btrfs rw,relatime,nodatasum,nodatacow,discard=async,space_cache=v2,subvol=/@home 0 0

# /dev/vda2
UUID=<uid of partion> /var/cache/pacman/pkg btrfs rw,relatime,nodatasum,nodatacow,discard=async,space_cache=v2,subvol=/@pkg 0 0

# /dev/vda2
UUID=<uid of partion> /var/log btrfs rw,relatime,nodatasum,nodatacow,discard=async,space_cache=v2,subvol=/@log 0 0
...

# btrfs subvol list /
ID 256 gen 73 top level 5 path @
ID 257 gen 9 top level 5 path @home
ID 258 gen 72 top level 5 path @log
ID 259 gen 65 top level 5 path @pkg
ID 260 gen 17 top level 256 path var/lib/portables
ID 261 gen 17 top level 256 path var/lib/machines

# ls -al /
total 24
drwxr-xr-x   1 root root  122 Oct 31 00:02 .
drwxr-xr-x   1 root root  122 Oct 31 00:02 ..
lrwxrwxrwx   1 root root    7 Oct 12 16:21 bin -> usr/bin
drwxr-xr-x   3 root root 4096 Jan  1  1970 boot
drwxr-xr-x  20 root root 3860 Oct 31 00:50 dev
drwxr-xr-x   1 root root 1828 Oct 31 00:50 etc
drwxr-xr-x   1 root root    0 Oct 31 00:01 home
lrwxrwxrwx   1 root root    7 Oct 12 16:21 lib -> usr/lib
lrwxrwxrwx   1 root root    7 Oct 12 16:21 lib64 -> usr/lib
drwxr-xr-x   1 root root    0 Oct 12 16:21 mnt
drwxr-xr-x   1 root root    0 Oct 12 16:21 opt
dr-xr-xr-x 228 root root    0 Oct 31 00:44 proc
drwx------   1 root root   74 Oct 31 00:51 root
drwxr-xr-x  19 root root  480 Oct 31 00:51 run
lrwxrwxrwx   1 root root    7 Oct 12 16:21 sbin -> usr/bin
drwxr-xr-x   1 root root   14 Oct 31 00:02 srv
dr-xr-xr-x  13 root root    0 Oct 31 00:44 sys
drwxrwxrwt   8 root root  160 Oct 31 00:44 tmp
drwxr-xr-x   1 root root   80 Oct 31 00:50 usr
drwxr-xr-x   1 root root  116 Oct 31 00:44 var

If you mount the actual root of the filesystem to /mnt, you can see the folders of the subvolumes there as well.

# mount /dev/vda2 /mnt

# ls -al /mnt/
total 16
drwxr-xr-x 1 root root    28 Oct 31 00:01 .
drwxr-xr-x 1 root root   164 Oct 31 14:58 ..
drwxr-xr-x 1 root root   164 Oct 31 14:58 @
drwxr-xr-x 1 root root     0 Oct 31 00:01 @home
drwxr-xr-x 1 root root   106 Oct 31 00:04 @log
drwxr-xr-x 1 root root 26052 Oct 31 01:10 @pkg

For now, my confusion about this is cleared up

richard-rumpel · 2025-10-31 16:48:09

But maybe someone can give me a few tips for my actual project.

I want to set up a small home server based on Arch Linux. It should function as a file server and also host a few virtual machines. The files should be accessible in the network via NFS and SMB.

The system has a 1TB SSD, where an installation following the LVM on LUKS scheme already exists. The root partition of the system is ext4, and the data partition under /data is supposed to use Btrfs.

The data should be organized according to the following scheme:

# currently relevant data
/data/documents snapshots every hour for the last 72 hours
weekly snapshots for the last 100 weeks

# backups that come from other systems
/data/backups no snapshots

# long-term data
/data/archive no snapshots
enable compression

# qemu disk images
/data/vm-images no snapshots
no copy-on-write (because of write amplification?)

This is how I would set up the whole thing:

                    
# lvcreate -n data -L900G vg00
# mkfs.btrfs /dev/vg00/data
# mkdir /mnt2
# mount /dev/vg00/data /mnt2
# btrfs subvol create /mnt2/@
# btrfs subvol create /mnt2/@documents
# btrfs subvol create /mnt2/@backups
# btrfs subvol create /mnt2/@archiv
# btrfs subvol create /mnt2/@vm-images
# cd /mnt2 
# mkdir @/documents @/backup @/archiv @/vm-images
# cd / && umount /mnt2 && rmdir /mnt2
# mkdir -p /data /nfs/data
# cat >> /etc/fstab
/dev/loop0              /data           btrfs           rw,relatime,ssd,discard=async,space_cache=v2,subvol=/@  0 0

/dev/loop0              /data/documents btrfs           rw,relatime,ssd,discard=async,space_cache=v2,subvol=/@documents 0 0

/dev/loop0              /data/vm-images btrfs           rw,relatime,ssd,discard=async,space_cache=v2,[b]nodatasum,nodatacow[/b],subvol=/@vm-images 0 0

/dev/loop0              /data/archiv    btrfs           rw,relatime,ssd,discard=async,space_cache=v2,[b]compress=zstd[/b],subvol=/@archiv    0 0

/dev/loop0              /data/backups   btrfs           rw,relatime,ssd,discard=async,space_cache=v2,subvol=/@backups   0 0

# bindmount for nfs server
/data/music /nfs/data  none   bind   0   0

First question: does this setup make sense to you, or would you suggest doing things a little differently?

Second question: How can I create a snapshot without a new folder appearing in the /data directory?
btrfs subvolume snapshot /data/documents/ <what to put here?>

Or maybe all of this is too complicated, and I should just create the filesystem, mount it directly under /data, and put the snapshots in subfolders like .data-snapshots/snap_<time>?

How would you do it?

pointerIs404 · 2025-11-03 08:00:10

richard-rumpel wrote:

But maybe someone can give me a few tips for my actual project.
I want to set up a small home server based on Arch Linux. It should function as a file server and also host a few virtual machines. The files should be accessible in the network via NFS and SMB.
The system has a 1TB SSD, where an installation following the LVM on LUKS scheme already exists. The root partition of the system is ext4, and the data partition under /data is supposed to use Btrfs.
The data should be organized according to the following scheme:
# currently relevant data
/data/documents snapshots every hour for the last 72 hours
weekly snapshots for the last 100 weeks
# backups that come from other systems
/data/backups no snapshots
# long-term data
/data/archive no snapshots
enable compression
# qemu disk images
/data/vm-images no snapshots
no copy-on-write (because of write amplification?)

This is how I would set up the whole thing:
                    
# lvcreate -n data -L900G vg00
# mkfs.btrfs /dev/vg00/data
# mkdir /mnt2
# mount /dev/vg00/data /mnt2
# btrfs subvol create /mnt2/@
# btrfs subvol create /mnt2/@documents
# btrfs subvol create /mnt2/@backups
# btrfs subvol create /mnt2/@archiv
# btrfs subvol create /mnt2/@vm-images
# cd /mnt2 
# mkdir @/documents @/backup @/archiv @/vm-images
# cd / && umount /mnt2 && rmdir /mnt2
# mkdir -p /data /nfs/data
# cat >> /etc/fstab
/dev/loop0              /data           btrfs           rw,relatime,ssd,discard=async,space_cache=v2,subvol=/@  0 0

/dev/loop0              /data/documents btrfs           rw,relatime,ssd,discard=async,space_cache=v2,subvol=/@documents 0 0

/dev/loop0              /data/vm-images btrfs           rw,relatime,ssd,discard=async,space_cache=v2,[b]nodatasum,nodatacow[/b],subvol=/@vm-images 0 0

/dev/loop0              /data/archiv    btrfs           rw,relatime,ssd,discard=async,space_cache=v2,[b]compress=zstd[/b],subvol=/@archiv    0 0

/dev/loop0              /data/backups   btrfs           rw,relatime,ssd,discard=async,space_cache=v2,subvol=/@backups   0 0

# bindmount for nfs server
/data/music /nfs/data  none   bind   0   0
First question: does this setup make sense to you, or would you suggest doing things a little differently?
Second question: How can I create a snapshot without a new folder appearing in the /data directory?
btrfs subvolume snapshot /data/documents/ <what to put here?>
Or maybe all of this is too complicated, and I should just create the filesystem, mount it directly under /data, and put the snapshots in subfolders like .data-snapshots/snap_<time>?
How would you do it?

Not quite an expert, but isn't it better to partition the drive, and mount each partition with your specific mount option and actual allocaced space ?

It's more work to set up but easier to maintain and tune

And for your /datahow could you have snapshot without, without a /data/. snapshots appearing, hum well you could edit the config for that path right after creating one with snapper if that's what you use, yo point out to another snapshot folder elsewhere

richard-rumpel · 2025-11-10 18:53:34

You were right. The idea with the subvolume was way too complicated. When I configured Snapper, it really backfired.

I've now decided on a simpler approach: two subvolumes, one for @vm-images and one '@' for everything else. This simplifies things significantly for all the following steps like NFS, Snapper, etc.

Thanks a lot for the feedback.

Arch Linux

#1 2025-10-29 13:29:27