OpenHVF

OpenHVF installs and manages OpenBSD virtual machines under QEMU. It fetches the install set, creates the disk, answers the installer over the serial console, and hands you back a machine that accepts SSH. One command, unattended, on a host that need not be running OpenBSD itself.

Anyone who has installed OpenBSD by hand to test one thing knows why this exists. OpenHVF turns that afternoon into openhvf up, and turns the result into something a Makefile can drive.

What it does

Unattended install

openhvf up downloads the release, creates the disk image, drives bsd.rd through the installer, and starts the machine. It is idempotent: run it again and nothing happens.

A project, not a global daemon

State lives beside the code, in an .openhvfrc file and an .openhvf/ directory found by searching upward from the current directory. Several machines can be defined per project, each with its own release, memory, disk and forwarded ports.

Cached install images

Release sets are cached under ~/.cache/openhvf/ and served to the guest through a built-in proxy, so the expensive download happens once rather than once per machine.

Scriptable, with honest exit codes

openhvf ssh runs a command in the guest and exits with its status; openhvf expect drives the serial console with an expect(1) script; a distinct exit code per failure mode — not running, timed out, download failed — means a script can tell what went wrong.

Whatever accelerator is there

HVF on macOS, KVM on aarch64 Linux, TCG everywhere else, chosen automatically and overridable with --emulate.

Where it came from

OpenHVF was written to run OpenHAP's integration tests on the platform they are about: pledge(2), unveil(2), rc.d and mdnsd cannot be tested anywhere else. Nothing in it knows that; it is a general utility, and this repository is simply its first user.

It ships with the OpenHAP source but not with OpenHAP: make install does not install it, and no release package contains it.

Reference

Every option, subcommand, exit code and configuration key is documented in the manual.