xsysroot · Albert Casals

What it does

xsysroot mounts, modifies, snapshots and repacks whole OS images for SBCs — Raspberry PIs, Beaglebones and friends — right from your x86 laptop or a tiny VPS. It binds image files through NBD, layers all changes into an incremental qcow2 file (your original image is never touched), and chroots into the result using QEMU user-mode ARM emulation, so apt-get, debuild and full installers run natively for the target architecture.

The 6-step Raspbian tutorial (original quickstart)

1. Blank image: xsysroot --geometry "raspbian.img fat32:40 ext4:800" — 40MB FAT32 boot + 800MB ext4 root.

2. Write a JSON profile (nbdev, sysroot, backing_image, qcow_image...).

3. Bind and mount: xsysroot --profile raspbian --renew — the qcow overlay is created from the pristine backing image; mount points appear on the host. Docs' own words: "wow... how scary!" — three things happened, all fine.

4. Install Debian in two stages:

$ sudo debootstrap --foreign --variant=minbase --arch=armhf jessie \
    $(xsysroot --query sysroot) http://mirror/raspbian/
$ sudo cp $(which qemu-arm-static) $(xsysroot -q sysroot)/usr/bin
$ xsysroot -x "/debootstrap/debootstrap --second-stage"

5. Firmware: xsysroot --chroot, point apt at Raspbian, install curl + binutils, run rpi-update, write cmdline.txt, set root password.

6. Bake and burn: qemu-img convert $(xsysroot --query qcow_image) raspbian-bootable.img then dd to the SD card. A one-gigabyte image with ~200MB free, tested on real hardware. No SD-card shuffling during the build.

Features

qcow2 snapshots — replay or roll back any number of changes; --renew returns to the pristine image
tmp sharing — bind a host directory into the guest for project files across chroot sessions
Security contexts: run as guest users via -x "@user bash"; --jail mode disables poweroff/shutdown/reboot inside the guest
Networking via /proc passthrough; DNS isolation by default (customizable)
Virtual displays: Xvfb screenshots or x11vnc streaming of GUI apps — one independent display per image
Partition expansion (--expand) with online resize2fs for ext2/3/4
Multiuser-safe: detects running processes to prevent concurrent mount fights on shared servers
Cooperative work: send only the small qcow between colleagues — deltas travel, backing images stay
Native Debian packaging: --skeleton, --depends, --build wrappers around debuild, natively or cross
Python bindings for full automation — one script builds entire distros (this is how PiLove was built)

Why it mattered

Every image served on this site — pipaOS builds, KivyPie 0.3 to 1.0, PiCute, PiLove, KanoUbuntu, even the weekly RaspiMirror builds — came out of xsysroot. It abstracted mount-image, chroot, build, snapshot, ship into one modest Python script and was later packaged for ArchLinux. Not bad for a tool named after its own quest.

xsysroot is free software. The complete documentation PDF — including the famous wow... how scary! debootstrap step and the QCow chapter — lives on GitHub.

🧰 xsysroot

What it does

The 6-step Raspbian tutorial (original quickstart)

Features

Why it mattered