How the vt_bootstrap Plugin Downloads Guest Images and Test Providers in Avocado-VT

The vt_bootstrap plugin orchestrates environment setup by cloning test provider git repositories and downloading, verifying, and decompressing guest OS images through the core virttest/bootstrap.py module.

The vt_bootstrap command is the standard entry point for initializing Avocado-VT test environments. When you run this command, the plugin delegates all heavy lifting to the underlying bootstrap framework, which handles both version-controlled test assets and binary guest images required for virtualization testing.

Entry Point: The VTBootstrap Plugin

The CLI command is implemented in avocado_vt/plugins/vt_bootstrap.py by the VTBootstrap class. When a user executes:

avocado vt-bootstrap [options]

The run() method collects parsed arguments and forwards them directly to the core bootstrap routine:

bootstrap.bootstrap(options=config, interactive=True)  # virttest/bootstrap.py

This single call triggers the complete setup workflow, separating the Avocado plugin interface from the domain-specific logic that manages test providers and guest images.

How Test Providers Are Downloaded and Configured

Test providers are git repositories containing test cases and configuration data. The bootstrap process ensures these are synchronized locally through three distinct phases.

Synchronizing the Provider Directory Structure

First, the bootstrap script establishes a writable local copy of the reference test providers. It copies the base provider directory to the user’s local data directory:

shutil.copytree(tp_base_dir, tp_local_dir, dirs_exist_ok=True)

The paths are resolved through data_dir.get_base_test_providers_dir() and data_dir.get_test_providers_dir() in virttest/data_dir.py, ensuring platform-agnostic path management.

Detecting Missing Providers

The system scans for providers that have never been cloned by checking for the absence of .git subdirectories. The function asset.test_providers_not_downloaded() in virttest/asset.py iterates through all entries in test-providers.d/:

not_downloaded = asset.test_providers_not_downloaded()

This returns a list of provider names requiring initial cloning.

Cloning and Updating Provider Repositories

If the user has not disabled downloads via --vt-no-downloads, the bootstrap calls asset.download_all_test_providers(update_flag). This function, located in virttest/asset.py, iterates through all provider names and invokes:

def download_all_test_providers(update=False):
    for provider in get_test_provider_names():
        download_test_provider(provider, update)

For each provider, the system:

1. Resolves the git URL from the provider’s provider.ini configuration file
2. Clones or updates the repository using git.get_repo() (or git pull when updating)
3. Verifies integrity by running git log -1 to confirm the repository is functional

How Guest Images Are Downloaded and Prepared

Guest images are binary assets defined in Cartesian configuration files. The bootstrap process parses these definitions, downloads the corresponding files, and prepares them for use.

Parsing Guest OS Requirements

For the selected virtualization type (--vt-type), the bootstrap code identifies required assets by parsing Cartesian configuration files. It calls:

get_guest_os_info_list(vt_type, guest_os)

This function reads guest-os.cfg (located via data_dir.get_backend_cfg_path()) to extract asset names such as JeOS.27.x86_64. The default guest OS and architecture are sourced from virttest/defaults.py (DEFAULT_GUEST_OS and ARCH constants).

Downloading and Verifying Assets

For each asset name, the system invokes:

asset.download_asset(os_asset, interactive=interactive, restore_image=True)

The download_asset() function in virttest/asset.py performs the following:

1. Loads asset metadata via get_asset_info(), parsing the corresponding .ini file
2. Checks SHA-1 integrity by comparing the local file hash against the sha1_url entry
3. Downloads when necessary using download.url_download_interactive() if the file is missing, corrupted, or mismatched
4. Handles decompression by calling uncompress_asset() for compressed archives (.xz, .gz)

The download_file() function encapsulates this logic:

def download_file(asset_info, interactive=False, force=False):
    # Verify SHA1, download if needed, then...

    uncompress_asset(asset_info, force=force)

Image Restoration

When restore_image=True is passed (the default in the bootstrap context), the system ensures the uncompressed image exists even if the compressed archive is already present. This guarantees the guest image is immediately ready for test execution without manual extraction.

Common Bootstrap Workflows

Run a basic bootstrap for the default QEMU backend:

avocado vt-bootstrap

Force a complete refresh of providers and re-download all assets:

avocado vt-bootstrap \
    --vt-update-providers \
    --vt-update-config \
    --yes-to-all

Programmatically trigger bootstrap from a custom script:

from virttest import bootstrap, defaults

options = {
    "vt.type": "qemu",
    "vt.guest_os": f"{defaults.DEFAULT_GUEST_OS}.{defaults.ARCH}",
}
bootstrap.bootstrap(options, interactive=False)

Summary

• Entry point: The VTBootstrap class in avocado_vt/plugins/vt_bootstrap.py forwards CLI arguments to virttest/bootstrap.py.
• Provider setup: The system clones git repositories listed in test-providers.d/ using functions in virttest/asset.py, synchronizing local copies with remote sources.
• Guest image handling: Cartesian configuration files define required assets; download_asset() verifies SHA-1 hashes, downloads missing files, and decompresses images automatically.
• Path management: virttest/data_dir.py centralizes all filesystem paths for downloads, providers, and configuration files.
• Defaults: virttest/defaults.py supplies standard guest OS identifiers and architecture strings used during bootstrap.

Frequently Asked Questions

Where does vt_bootstrap store downloaded guest images?

According to the avocado-vt source code, guest images are stored in the directory returned by data_dir.get_download_dir(), typically located under ~/avocado/data/avocado-vt/downloads/ or the system-wide Avocado data directory. The specific path varies by platform and Avocado configuration, but all locations are centralized through virttest/data_dir.py.

Can I run vt_bootstrap without downloading anything?

Yes. Pass the --vt-no-downloads flag to skip all network operations. In this mode, the bootstrap script still synchronizes the test provider directory structure and verifies local asset integrity, but it will not clone new git repositories or download missing guest images. This is useful for offline environments where assets are pre-staged manually.

How does vt_bootstrap verify the integrity of downloaded files?

The bootstrap process uses SHA-1 verification implemented in virttest/asset.py. For each asset, the download_file() function retrieves the expected hash from the sha1_url field in the asset’s .ini configuration file. It computes the local file’s SHA-1 hash and compares it; if the hashes mismatch or the file is missing, it triggers a fresh download via download.url_download_interactive().

What virtualization backends does vt_bootstrap support?

The vt_bootstrap command supports any backend defined in the Avocado-VT Cartesian configuration files, including qemu, libvirt, and lvsb. You specify the target backend using the --vt-type option (e.g., --vt-type qemu). The bootstrap code then loads the corresponding guest-os.cfg from the backend-specific directory to determine which guest images to download.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}