FuguVM

Install and manage OpenBSD virtual machines under QEMU, by hand or by agent.

The tool exists so a test suite can run against a real OpenBSD guest, on a Linux or Darwin host and in CI.

fuguvm installs a guest without interaction, caches the installed disk, and drives the lifecycle: boot, wait, ssh, snapshot, and shutdown. fuguvm image export publishes an installed image as a file, and a base_disk directive consumes that file on an other host. A project describes its guests in one .fuguvmrc at its root.

FuguVM uses Perl (v5.36) over the Fugu library. It adds no direct CPAN dependency of its own. The specification in spec/ states the design.

Quick start

make deps
bin/fuguvm up && bin/fuguvm wait
bin/fuguvm ssh -- uname -a
bin/fuguvm down

make deps installs the latest Fugu release, QEMU, and the SSH and HTTP modules the optional features use. See INSTALL.md for full instructions.

make deps verifies every download. The Fugu release carries a signed SHA256 manifest, and deps/KEYS.txt declares the release key of the organization by URL and digest. scripts/deps fetches that key, holds it to the digest, and verifies the manifest with signify(1). deps/SHA256.txt records the digest of each other download.

make deps also installs gitleaks, the tool of the secret gate. It installs the tool environment before every other environment, so the gate tool is present for each chain. The CI gate installs gitleaks with make deps, so one pin serves the operator gate and the CI gate.

Documentation

man fuguvm — or mandoc man/fuguvm/fuguvm.1 | less from a checkout — holds the full command, option, and exit-code reference. Each module documents its API in a .pod sidecar; start with lib/App/FuguVM.pod.

Commands

make check          # lint + format + test + spec-check + ste-lint + gitleaks
make test           # prove -l t/{fuguvm,scripts,ci}/*.t
prove -l t/fuguvm/foo.t    # one test file
make format-fix     # auto-fix the Perl, Markdown, JSON and YAML formatting
make dist           # build the release tarball

make check runs the Markdown format gate, and prettier runs through bunx. The operator installs bun and gitleaks, for example from Homebrew. No deps manifest provides them.

The tests need the Fugu library on @INC; a local build of the sibling checkout works too: cpanm --local-lib=local ../Fugu/build/Fugu-*.tar.gz.

Releases

Push a v<MAJOR>.<MINOR>.<PATCH> tag, and the release workflow publishes the tarball to GitHub Releases and to PAUSE. The rules are in spec/release.md.

Commit scopes

cli, config, console, disk, guest, miniroot, mirror, proxy, qmp, remote, state, spec, deps, ci.

License

ISC. See LICENSE.