Linux – 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?

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