Explore Btrfs images on MacOS

While troubleshooting a malfunctioning radar system, I wanted to inspect its firmware for diagnostic tools (couldn’t find any). The firmware was stored in a Btrfs image, which isn’t straightforward to handle on macOS without spending some quality time with FUSE.

To “extract” its contents, I instead used a Docker container with the necessary tools, because it’s quite easy to do on plain linux. Here’s how.

1. Prepare Directories

Create directories to mount the image and store extracted files:

mkdir -p mnt output

2. Run Docker Container

Use a privileged Docker container to access loop devices and mount the Btrfs image:

docker run --rm --privileged \
  -v "$PWD/root.img:/root.img" \
  -v "$PWD/output:/output" \
  ubuntu bash -c "
    apt-get update && \
    apt-get install -y btrfs-progs && \
    mkdir -p /mnt && \
    loop=\$(losetup -f /root.img --show) && \
    mount \$loop /mnt && \
    cp -a /mnt/. /output/ && \
    umount /mnt && \
    losetup -d \$loop && \
    echo 'Files extracted to ./output'"

3. Verify Extraction

After the process, check the output directory on your host:

ls -l output/

What does it do ?

1. Install btrfs-progs: Installs the necessary tools to work with Btrfs filesystems.
2. Create Mount Point: Sets up the /mnt directory as the mount point.
3. Attach Loop Device: Associates the root.img file with a loop device.
4. Mount the Image: Mounts the loop device to /mnt.
5. Copy Files: Copies all contents from the mounted image to the /output directory.
6. Cleanup: Unmounts the image and detaches the loop device.

PS: If you don’t have it yet. Orbstack is awesome for all your docker/VM needs.