Skip to content

Latest commit

 

History

History
130 lines (90 loc) · 4.78 KB

testing.md

File metadata and controls

130 lines (90 loc) · 4.78 KB

Testing

Image tests must prove the artifact boots and that the baseline controls are active. Static validation alone is not enough for release-quality images.

Commands

make validate
make build
make test
make lint

make test expects the generated QCOW2 artifact at:

artifacts/ubuntu-24.04-base/ubuntu-24.04-base.qcow2

Automated Checks

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 docker module is enabled).
  • Node.js is not installed.
  • PHP is not installed (unless the cyberpanel module is enabled).

For profiles that include additional modules, the same test harness also verifies:

  • Fail2Ban SSH jail is active when fail2ban is enabled.
  • persistent journald configuration exists when logging is enabled.
  • auditd is active when audit is enabled.
  • selected sysctl hardening values are applied when hardening is enabled.
  • Docker daemon is active, enabled, has Docker Compose installed, and has live-restore and log limits pre-configured in /etc/docker/daemon.json when docker is enabled.

Static Checks

Use make doctor before building. If shellcheck is installed, run it against module and script files:

make lint

make inspect prints the selected profile, version, module list, and qemu-img info output when the artifact exists.

Manual Local Verification

To run a built image locally for manual testing, debugging, or configuration changes, use the scripts/run-vm.sh helper script.

Launching the VM

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.qcow2

This helper script automatically:

  1. Creates a temporary, isolated overlay image so the master image remains pristine.
  2. Injects a temporary SSH key and sets up login credentials via an automatically generated cloud-init seed ISO.
  3. Spawns the QEMU virtual machine.
  4. Forwards network ports to the host (e.g., SSH to 2222, HTTP to 8080, HTTPS to 8443, CyberPanel to 8090).

Accessing the VM (Credentials)

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: ubuntu
Password: ubuntu
Password: ubuntu
Or SSH Key: ssh -i build/run-vm/id_ed25519 -p 2222 ubuntu@127.0.0.1
root Username: root
Password: ubuntu
(Direct root SSH login is blocked by SSH policy; log in as ubuntu and run sudo -i)

1. On-Screen GUI Console Login

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:

QEMU Linux Boot Console

2. Network SSH Login

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

Programmatic Console Screenshot Capture

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.png

Reliable Test Orchestration (QEMU Guest Agent)

The automated test harness (make test) utilizes the QEMU Guest Agent (QGA) to ensure reliability:

  1. Instead of aggressively polling SSH (which can trigger UFW's limit rate-limiter, blocking the host IP and hanging the test suite), the host waits for the QGA socket at build/test-vm/qga.sock to become responsive.
  2. It executes cloud-init status --wait directly inside the VM using the QGA JSON-RPC protocol.
  3. Once the VM has fully finished provisioning, a single SSH multiplex master connection (ControlMaster) is opened.
  4. All integration assertions are run sequentially over the multiplexed connection, using zero additional TCP handshakes, completely avoiding rate-limit lockout.