Image tests must prove the artifact boots and that the baseline controls are active. Static validation alone is not enough for release-quality images.
make validate
make build
make test
make lintmake test expects the generated QCOW2 artifact at:
artifacts/ubuntu-24.04-base/ubuntu-24.04-base.qcow2
The initial test harness boots the image with QEMU and verifies:
- cloud-init completes.
- SSH is reachable with an injected test key.
- SSH service is active.
- qemu guest agent is active and enabled.
- UFW is active.
- Fail2Ban is active.
- unattended upgrades configuration exists.
- Docker is not installed (unless the
dockermodule is enabled). - Node.js is not installed.
- PHP is not installed (unless the
cyberpanelmodule is enabled).
For profiles that include additional modules, the same test harness also verifies:
- Fail2Ban SSH jail is active when
fail2banis enabled. - persistent journald configuration exists when
loggingis enabled. - auditd is active when
auditis enabled. - selected sysctl hardening values are applied when
hardeningis enabled. - Docker daemon is active, enabled, has Docker Compose installed, and has live-restore and log limits pre-configured in
/etc/docker/daemon.jsonwhendockeris enabled.
Use make doctor before building. If shellcheck is installed, run it against module and script files:
make lintmake inspect prints the selected profile, version, module list, and qemu-img info output when the artifact exists.
To run a built image locally for manual testing, debugging, or configuration changes, use the scripts/run-vm.sh helper script.
You can boot the virtual machine in either Headless or GUI mode:
# Headless mode (default)
./scripts/run-vm.sh <path-to-qcow2-image> [ssh_port] [http_port] [https_port] [cyberpanel_port]
# GUI window mode (displays the Linux VM console directly on your desktop)
GUI=1 ./scripts/run-vm.sh <path-to-qcow2-image>Example:
GUI=1 ./scripts/run-vm.sh artifacts/ubuntu-24.04-base/ubuntu-24.04-base.qcow2This helper script automatically:
- Creates a temporary, isolated overlay image so the master image remains pristine.
- Injects a temporary SSH key and sets up login credentials via an automatically generated cloud-init seed ISO.
- Spawns the QEMU virtual machine.
- Forwards network ports to the host (e.g., SSH to
2222, HTTP to8080, HTTPS to8443, CyberPanel to8090).
For development ease, the local VM setup configures password access for both the default user and the administrative root user, while preserving SSH-key options.
| Account | Console Login (GUI TTY) | SSH Login (Network) |
|---|---|---|
ubuntu |
Username: ubuntuPassword: ubuntu |
Password: ubuntuOr SSH Key: ssh -i build/run-vm/id_ed25519 -p 2222 ubuntu@127.0.0.1 |
root |
Username: rootPassword: ubuntu |
(Direct root SSH login is blocked by SSH policy; log in as ubuntu and run sudo -i) |
When running with GUI=1, QEMU opens a graphical display showing the interactive Linux console. You can log in directly at the prompt using the credentials above:
To connect remotely via terminal, you can log in using either the password ubuntu or the auto-generated SSH key:
-
Using Password:
ssh -p 2222 ubuntu@127.0.0.1 # When prompted, enter password: ubuntu -
Using SSH Key:
ssh -i build/run-vm/id_ed25519 -p 2222 ubuntu@127.0.0.1
To programmatically capture screenshots of the running VM's console (for automated testing or visual documentation), use the scripts/capture-console.py tool. It queries the QEMU monitor socket and dumps the frame buffer to a PNG:
python3 scripts/capture-console.py build/run-vm/monitor.sock docs/assets/vm_console.pngThe automated test harness (make test) utilizes the QEMU Guest Agent (QGA) to ensure reliability:
- Instead of aggressively polling SSH (which can trigger UFW's
limitrate-limiter, blocking the host IP and hanging the test suite), the host waits for the QGA socket atbuild/test-vm/qga.sockto become responsive. - It executes
cloud-init status --waitdirectly inside the VM using the QGA JSON-RPC protocol. - Once the VM has fully finished provisioning, a single SSH multiplex master connection (
ControlMaster) is opened. - All integration assertions are run sequentially over the multiplexed connection, using zero additional TCP handshakes, completely avoiding rate-limit lockout.
