Reference VM

The Reference VM is a Debian-based VM image used for testing ChromeOS VM integrations.

Dependencies

Debian:

sudo apt install eatmydata fai-setup-storage lvm2 ovmf python3-jinja2 \
  python3-requests python3-yaml

For creating the UEFI variables image:

pip3 install --user virt-firmware

Build instructions

sudo ./build.py

sudo is required for loopback device use.

Incremental Updates

If you only need to update configuration files (e.g., systemd units, scripts in data/) without rebuilding the entire OS or re-installing packages, you can use the incremental mode:

sudo ./build.py --update-config-only

This will:

• Reuse the existing refvm.img.
• Skip debootstrap and package installation.
• Skip kernel module compilation (DKMS).
• Only apply changes from the data/ directory and refresh systemd configuration.

What is updated:

• Files in the data/ directory (copied to the image).
• GRUB configuration (update-grub).
• systemd configuration (scripts in data/ that refresh units).

What is NOT updated:

• The base OS and installed packages (skips apt-get install).
• Kernel and kernel modules (skips DKMS).
• The status reporter binary (skips Go build).
• User accounts and home directory files (except for .profile modifications if it's the first run).

This is significantly faster for quick iterations on configuration changes.

UEFI variables preparation

virt-fw-vars --input /usr/share/OVMF/OVMF_VARS_4M.fd \
  --output refvm_VARS.fd \
  --enroll-generate "reference VM PK/KEK" \
  --secure-boot \
  --add-mok "$(uuidgen -r)" ./data/var/lib/dkms/mok.pub

Secure Boot

The built image and firmware support UEFI Secure Boot. To load out-of-tree modules (currently virtio_wl and tpm_virtio), a signing key is included in the built image at /var/lib/dkms/mok.key. The variables image generated using the above command includes the public key in the MOK.

Booting in crosvm directly

A build of OVMF for crosvm (CROSVM_CODE.fd) is required. To run a basic VM with a serial console:

crosvm run --cpus 4 --mem 4096 --disable-sandbox --bios CROSVM_CODE.fd \
  --pflash refvm_VARS.fd --block path=/mnt/refvm.img \
  --serial type=stdout,console,stdin,earlycon

To enable networking, refer to the crosvm guide .

Booting on ChromeOS

Refer to go/bruschetta-installer on how to boot on ChromeOS.

Uprev

Uprev script will update the copy of reference_vm image to the latest one built in kokoro.

Install dependencies

sudo apt install brotli

Run the uprev script and commit the result.

repo start refvm-uprev-xxxx src/platform/tast-tests
cd src/platform2/vm_tools/reference_vm/
./uprev.sh
cd -
cd src/platform/tast-tests
git commit -a
cros_sdk tast run $DUT bruschetta.Basic  # try running test locally.

Local Experimentation

If you want to test your local changes in reference_vm with tast-tests, you can use run_experiment.sh. This script automates processing your local image and updating the local tast-tests data dependencies to use your local file directly (bypassing the need to upload to GCP).

# First, build the image (requires sudo)
sudo ./build.py

# Then, process it and update Tast tests
./run_experiment.sh [path/to/refvm.img]

By default, it looks for refvm.img in the current directory.

This script will:

1. Sparsify and convert the provided image to qcow2.
2. Compress the image using brotli (required by the Tast fixture).
3. Copy the image directly to the src/platform/tast-tests/.../bruschetta/data/ directory.
4. Update the local SHA256 hash and remove .external metadata so Tast uses the local file.

After running the script, you can run Tast tests as usual:

(chroot) tast run $DUT bruschetta.Basic

IMPORTANT: Do not commit the changes made by this script to the tast-tests repository (e.g., the refvm.qcow2 image or the updated SHA256 file). These changes are for local experimentation only. Use uprev.sh for official image updates.

Commit message can be something like:

bruschetta: uprev to refvm-xxx

BUG=b:366103608
TEST=cros_sdk tast run $DUT bruschetta.Basic