vm_tools/reference_vm/README.md

# Reference VM

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

## Dependencies

Debian:

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

For creating the UEFI variables image:

```sh
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](https://crosvm.dev/book/running_crosvm/example_usage.html#add-networking-support)
.

## Booting on ChromeOS

Refer to [go/bruschetta-installer](https://goto.google.com/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).

```bash
# 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:
```bash
(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
```