Getting started¶

Host prerequisites¶

Install Python 3.8 or newer, QEMU for x86, and GNU Screen. On Debian or Ubuntu, a typical host setup is:

sudo apt update
sudo apt install qemu-system-x86 screen
test -r /dev/kvm && test -w /dev/kvm

The final command checks whether the current user can access KVM. Configure the host's KVM permissions before starting a VM if it fails.

Install the package¶

python3 -m pip install --upgrade syzqemuctl
syzqemuctl --version

Initialize an image home¶

Choose a directory that will contain the downloaded create-image.sh, the template image, and all derived images:

syzqemuctl init --images-home /home/user/syz-images --wait

New image homes default to Debian Trixie. Select an older userspace explicitly when required by a historical kernel:

syzqemuctl init \
  --images-home /home/user/syz-images \
  --distribution bullseye \
  --wait

--wait keeps the command attached until template creation finishes. Without it, template creation runs in a background screen session. Inspect progress with:

syzqemuctl status image-template

The selected image home is stored in ~/.config/syzqemuctl/settings.json.

Create an image¶

syzqemuctl create my-image

This copies the default ready template. To request a different disk size in megabytes:

syzqemuctl create my-image-4096 --size 4096

To build an image with a release different from the default template:

syzqemuctl create old-kernel-image --distribution bullseye

Distribution-and-size-specific templates are cached. Their first creation can continue in the background, so check syzqemuctl status my-image-4096 before using the image. Existing v0.3.x Bullseye templates remain the default for their image home until explicitly rebuilt.

See Image distributions for compatibility, layout, provenance, and upgrade details.

Start a VM¶

Pass the directory containing a built Linux kernel tree. The expected kernel image is arch/x86/boot/bzImage below this directory.

syzqemuctl run my-image --kernel /home/user/linux
syzqemuctl status my-image

Wait for the status to become Running before using SSH operations. The first boot can take several minutes depending on the guest and host.

Execute and copy¶

syzqemuctl exec --timeout 30 my-image "uname -a"
syzqemuctl cp --timeout 600 ./poc my-image:/root/poc
syzqemuctl cp --timeout 600 my-image:/root/vm.log ./vm.log

The timeout is a total operation limit. Omit it for an operation whose duration is intentionally unbounded.

Stop and delete¶

syzqemuctl stop my-image --wait --timeout 20
syzqemuctl delete my-image

Use --force only when normal cleanup cannot remove stale runtime state:

syzqemuctl stop my-image --wait --force --timeout 20