How does libguestfs live work?

First a quick refresher on how libguestfs works. Normally when you run libguestfs on a disk image, we launch a qemu process running a small custom appliance. Inside the appliance is a Linux kernel, Linux userspace tools (like mkfs, parted, LVM), and a daemon called guestfsd.

By the way, it’s a common mistake for people to think that the qemu process is the virtual machine. It’s not the VM. It’s a custom, minimal appliance containing our own tools, and the VM is not running.

Although we used fork to run qemu, we don’t talk to the daemon over stdin/stdout. We use a fast virtio-serial port instead.

Across the virtio-serial port, we send simple commands using an efficient XDR-based remote protocol. Many libguestfs API functions directly map to remote procedure calls in this protocol.

For example, calling guestfs_mkfs in the library, translates to a mkfs remote procedure call over the virtio-serial port, and ultimately guestfsd runs the mkfs command inside the appliance.

Libguestfs live is a simple extension of this idea. Instead of running our own qemu and connecting to a virtio-serial port, how about we allow libguestfs to attach to any existing port? We rely on someone else to start up a guest, install guestfsd in it, and set up the virtio-serial ports, and we just attach to them:

At the API level, everything works very much the same. You still have to call guestfs_launch. But if you changed the attach method from the default (launching a new qemu) to connecting to unix:path, launch will just connect to the named Unix socket. guestfsd is expected to be on the other end of this socket, so usually you want to have this socket be a virtio-serial port. Then you just send ordinary libguestfs commands, which the daemon runs for you inside the guest.