BTRFS explorer - view the layout of your data on disk

To better understand the on-disk format of BTRFS (one of the main file systems used in Linux) I wrote a parser for it and added a simple web interface. Maybe this can be useful for anyone else trying to understand BTRFS by allowing to look at a concrete example. I also tried to add explanations at some points, but they could be more detailed.

Online demo

This is just a 3 GiB image which contains a base installation of Arch Linux. And I took a snapshot called "freshinstall". The tool offers a few different views:

• The chunks: this shows the layout of the physical disk. It is split into "chunks" which are a few hundred megabytes in size and can contain data or metadata. Click on one of the metadata chunks to see how the B-trees are laid out in them. To see what is actually contained in these trees, use the "root tree" view below.
• The root tree: this shows the metadata on a higher level: the B-trees form a key-value store which stores all kinds of data like files, directories, subvolumes, checksums, free space etc. The "root tree" is the highest level node from which you can click through all the other trees. The most interesting is tree 5 (the filesystem tree) with which you can browse through the entire filesystem (although it currently doesn't show the contents of large files).
• The chunk tree: this tree with the ID 3 is a bit special in that it's not listed in the root tree (it also lives in the system chunks instead of the metadata chunks). It contains the mapping between virtual and physical addresses, providing the "device mapper" and RAID functionality of BTRFS. The "chunks" overview above is really just showing the contents of this tree.

Using your own data

To install this, clone the repository, get Rust, and run

cargo build --release

which creates a standalone binary at the path target/release/btrfs_explorer_bin.

Now you can just run the btrfs_explorer_bin binary. It takes two arguments: the first is a disk image and the second (optional) argument is the address the web server should listen at, in the format address:port. The default is localhost:8080.

Then visit the address (e.g. http://localhost:8080) in a browser to see the chunk view, and http://localhost:8080/tree/1 for the root tree view, etc.

Ideally it should be possible to use this on block devices, even mounted ones, but at the moment that has a few issues, so I would recommend only looking at images (it never writes anything, so at least it should never destroy any data, but there might be crashes).