btrfs: browsing subvolumes

I am new to btrfs, and confused about subvolumes, after reading the documentation and experimenting on a local system. I have a Linux Mint system with a btrfs root partition. Mint conveniently includes a tool that helps automate regular snapshots. I can easily list the ones it has made and kept.

$ sudo btrfs subvolume list /
ID 257 gen 52540 top level 5 path @
ID 258 gen 52540 top level 5 path @home
ID 283 gen 52467 top level 5 path timeshift-btrfs/snapshots/2019-01-15_02-00-51/@
ID 286 gen 50026 top level 5 path timeshift-btrfs/snapshots/2019-01-16_02-00-01/@
ID 288 gen 50026 top level 5 path timeshift-btrfs/snapshots/2019-01-17_02-00-01/@
ID 289 gen 50026 top level 5 path timeshift-btrfs/snapshots/2019-01-18_02-00-01/@
ID 291 gen 50409 top level 5 path timeshift-btrfs/snapshots/2019-01-19_02-00-01/@

Based on the documentation, however, I understand that snapshots can be browsed, their full tree exposed just as the main file tree, appearing as directories to the application. I could, for example, copy a single file from the snapshot to the mounted top-level volume. That is, from an application perspective, making a snapshot is much like an atomic, recursive copy.

However, I am able to find none of the seven subvolumes listed above in the contents either of / or /home, and no entry called timeshift-btrfs appears in the listing of /home.

What am I misunderstanding? Is there any directory listing that shows the tree of the snapshots?

1 Answer

Keep in mind the Btrfs directory (and subvolumes) tree on your device is conceptually different than the directory structure in the OS. The root of either one is denoted / but they are different.

The @ subvolume is identified within the Btrfs filesystem itself as @ (or /@) but this path is not directly available in your OS. I guess the subvolume is mounted to / which is the root of your directory tree as seen by the OS and programs (note: mount namespaces aside).

Similarly @home is mounted under /home.

The output of mount command in my Kubuntu contains (among other lines):

/dev/sda1 on / type btrfs (rw,relatime,ssd,space_cache,subvolid=1902,subvol=/@)
/dev/sda1 on /home type btrfs (rw,relatime,ssd,space_cache,subvolid=258,subvol=/@home)

So my setup is identical as yours: /@ subvolume from Btrfs tree becomes / in the OS tree. /@home subvolume from Btrfs tree becomes /home in the OS tree.

But I also have access to the entire Btrfs tree:

/dev/sda1 on /mnt/ssd type btrfs (rw,relatime,ssd,space_cache,subvolid=5,subvol=/)

This means the root (/) of the Btrfs tree is available as /mnt/ssd in my OS. From there I can peek into every subvolume and directory. I set this mountpoint up by myself, exactly to be able to see and manage the entire Btrfs structure. The relevant line in my /etc/fstab is as follows:

UUID=<UUID of my /dev/sda1 here> /mnt/ssd btrfs defaults,subvol=/ 0 2

Even without the above line I could still mount the root Btrfs volume manually:

mount -o rw,relatime,ssd,space_cache,subvol=/ /dev/sda1 /mnt/ssd

The main conclusion is you should mount the root of your Btrfs filesystem somewhere, with subvol=/ option. This way you gain access to the filesystem in its entirety.

Note it's a good idea not to mount Btrfs / as your OS /. If such mounting was the case, you had /etc, /bin etc. directories directly under your Btrfs / along with subvolumes like /timeshift-btrfs. In your OS all these entries would appear under / after mounting the Btrfs / to the OS /.

By deriving your OS's root tree from Btrfs /@ you keep it tidy. You (and/or proper tools) organize subvolumes outside Btrfs /@, while the OS keeps the majority of its / in Btrfs /@. Majority, because e.g. in my case /mnt/ssd/@/proc is just an empty directory (after Btrfs /@ is mounted as /, the proc filesystem is available in the OS's /proc); the same for /mnt/ssd/@/home (after Btrfs /@ is mounted as /, the Btrfs /@home subvolume gets mounted at what's now the OS's /home).