Chrooting into BTRFS


I was trying to rescue my new Manjaro installation. But, I had never tried chrooting into a BTRFS volume before.


chroot lets you rebase the file system from a running system (like a live USB flash drive) to the file system of a stopped system (like a broken Linux installation on your hard drive). By changing the root (chroot), utilities run inside the chrooted environment act as if they were being run on the computer that you are troubleshooting. So, if my Manjaro installation is not working, I can use my installation disc, chroot into my system, and run updates, check the logs, or run other utilities. In this way, chroot combines the functioning of the live system with the file system of the broken installation.


Note that chroot is a terminal command. And only terminal commands run from a chrooted shell will affect the troubled system. Graphical utilities will affect the live system.


After mounting the troubled file system, what confused me were the "@" directories. There were entries like @, @home, @log, and @cache. The names were familiar to me. These are common directories on Linux. What I did not understand was the significance of @ and how that related to BTRFS.


What are @ Directories?


Directories preceded with @ are subvolumes in BTRFS. For example, @ (the root directory), @home, @log (/var/log), and @cache (/var/cache).


As far as I can tell, @ doesn't have any special meaning. It is just a naming convention used to differentiate subvolumes from other directories. This naming convention ended up helping me by giving me something to search for online. But, in principle, subvolumes can look just like normal directories.


I first saw @ directories by directly mounting the BTRFS volume and listing its contents. Below, I mount my BTRFS volume from /dev/nvme0n1p2 which represents a partition on my NVMe drive. Your drive and partition will be different. For example, /dev/sda1 would represent a SATA drive and partition.


# Open a terminal. 
# Log in as root on the live system. 
sudo -i 
# Make a directory to mount the file system to. 
mkdir /chroot
# Mount the file system. 
mount /dev/nvme0n1p2 /chroot
# List the contents of the file system. 
ls -l /chroot


I don't have a working example at the moment. But, listing the contents of /chroot should produce directories like @, @home, @log, and @cache.


While the BTRFS volume is mounted like this, you can also use the btrfs command to list the subvolumes. For example, this would be helpful if the subvolumes did not use @ in their names and there was no other way to tell which directories were subvolumes.


# List the subvolumes at the mount point I created. 
btrfs subvolume list /chroot


Note that the BTRFS volume is useless to us in this configuration. So, we unmount the volume as a last step.


umount /chroot



How to chroot into BTRFS


To get chroot working, I had to combine advice from different sources.


Below are the commands that worked for me on my NVMe drive.


The key is using the subvol= mount option to specify the BTRFS subvolume. Then, attach that subvolume to the correct location in the file system.

For example, @home to /chroot/home



# Skip these first two steps if you've already done them. 
#sudo -i 
#mkdir /chroot
# Mount the boot partition. Note I'm mounting ...n1p1 instead of n1p2. 
mount /dev/nvme0n1p1 /chroot/boot/efi 
# Mount the root subvolume. 
mount /dev/nvme0n1p2 /chroot/ -o subvol=@
# Mount the /home, /var/log, and /var/cache subvolumes. 
mount /dev/nvme0n1p2 /chroot/home      -o subvol=@home
mount /dev/nvme0n1p2 /chroot/var/log   -o subvol=@log
mount /dev/nvme0n1p2 /chroot/var/cache -o subvol=@cache
# Clone the hardware devices into the chroot environment. 
mount --bind /dev  /chroot/dev
mount --bind /sys  /chroot/sys
mount --bind /proc /chroot/proc
# Copy the network configuration from the live system. Note the trailing slash for /etc/
cp /etc/resolv.conf /chroot/etc/

# Finally, chroot. 
chroot /chroot


Now you are chrooted into the host file system. And, you can run utilities like pacman as if the host system were working.


Since we are in a live system, you can simply reboot when you are done. All the changes above are specific to that ephemeral system and will be discarded after rebooting.


If you want to interact with the live system while working, simply open a new terminal or use the graphical desktop environment.



References


chroot | Wikipedia

How to mount a device in Linux? | Unix & Linux Stack Exchange

What does the "@" symbol mean when in front of a directory, e.g. "@home"? | Comment Link | Ask Ubuntu

Subvolumes | BTRFS Documentation

[HowTo] Chroot from or into any Linux distribution | Tutorials | Manjaro Linux Forum

OS Chroot 101: Covering BTRFS Subvolumes | Fedora Magazine


Created: Sunday, June 25, 2023

Updated: Sunday, June 25, 2023




/gemlog/