How the vt_list_guests Plugin Discovers and Displays Available Guest Operating Systems

The vt_list_guests plugin discovers available guest operating systems by parsing the machines.cfg and guest-os.cfg configuration files for the selected backend, applying optional filters for architecture and OS type, and verifying whether the corresponding disk images exist on disk before displaying the results.

The vt_list_guests command is a core utility in the avocado-vt testing framework that enumerates usable guest OS images for virtualization testing. According to the avocado-framework/avocado-vt source code, the plugin operates through a three-stage pipeline that bridges configuration parsing with filesystem validation to present an accurate list of available guests.

CLI Command Registration and Option Parsing

The plugin entry point resides in avocado_vt/plugins/vt_list_guests.py, where the VTListGuests class registers command-line options during the configuration phase.

# avocado_vt/plugins/vt_list_guests.py

settings.register_option(section, key="guest_os", default=None,
                        help_msg="List only specific guests")
add_option(parser, dest="vt.list_guests.guest_os", arg="--guest-os")
add_option(parser, dest="vt.type", arg="--vt-type")

The --guest-os flag allows users to filter for specific operating systems, while --vt-type specifies the backend (e.g., qemu or libvirt). During execution, the run method invokes the discovery chain:

guest_name_parser = get_guest_name_parser(
    config, guest_os="vt.list_guests.guest_os")
guest_listing(config, guest_name_parser)

Guest Name Parsing and Configuration Loading

The get_guest_name_parser() function in virttest/standalone_test.py builds a Cartesian configuration parser that reads backend-specific definitions.

machines_cfg_path = data_dir.get_backend_cfg_path(
    get_opt(options, "vt.type"), "machines.cfg")
guest_os_cfg_path = data_dir.get_backend_cfg_path(
    get_opt(options, "vt.type"), "guest-os.cfg")
cartesian_parser.parse_file(machines_cfg_path)
cartesian_parser.parse_file(guest_os_cfg_path)

Backend Configuration Files

The parser loads two critical files:

• machines.cfg: Defines machine types and hardware profiles supported by the backend
• guest-os.cfg: Contains operating system definitions and their associated parameters

Filter Application

After parsing, the system applies filters based on user-provided constraints:

• vt.common.arch – Target architecture (e.g., x86_64, aarch64)
• vt.common.machine_type – Specific machine variant
• vt.list_guests.guest_os – Operating system name filter

Image Verification and Output Generation

The guest_listing() function in avocado_vt/loader.py iterates over the parsed guest definitions and performs filesystem validation.

for params in guest_name_parser.get_dicts():
    base_dir = params.get("images_base_dir", data_dir.get_data_dir())
    image_name = storage.get_image_filename(params, base_dir)
    machine_type = get_opt(config, "vt.common.machine_type")
    name = params["name"].replace(".%s" % machine_type, "")
    if os.path.isfile(image_name):
        out = name
    else:
        missing = "(missing %s)" % os.path.basename(image_name)
        out = name + " " + output.TERM_SUPPORT.warn_header_str(missing)
    LOG.debug(out)

For each guest definition yielded by the parser:

1. Image Path Resolution: storage.get_image_filename() constructs the absolute path to the disk image using the images_base_dir parameter or the default data directory.
2. Existence Check: The code verifies whether the image file exists using os.path.isfile().
3. Name Normalization: The machine type suffix is stripped from the guest name for cleaner display.
4. Output Generation: Available guests display their name only; missing images append a colored warning indicating the missing filename.

Practical Usage Examples

List all guests for the default QEMU backend:

avocado vt-list-guests

Filter for a specific operating system:

avocado vt-list-guests --guest-os fedora30

Specify an alternative backend:

avocado vt-list-guests --vt-type libvirt

Sample output indicating both available and missing images:

fedora30
centos7 (missing centos7-64.qcow2)
ubuntu20.04

Summary

• The plugin registers --guest-os and --vt-type CLI options in avocado_vt/plugins/vt_list_guests.py to control filtering and backend selection.
• Guest definitions are loaded from machines.cfg and guest-os.cfg via get_guest_name_parser() in virttest/standalone_test.py.
• The Cartesian parser applies filters for architecture (vt.common.arch), machine type (vt.common.machine_type), and specific guest OS names.
• guest_listing() in avocado_vt/loader.py validates image existence using storage.get_image_filename() and os.path.isfile().
• The output displays normalized guest names, appending warnings for any missing disk image files.

Frequently Asked Questions

What configuration files does vt_list_guests use to discover guest operating systems?

The plugin reads machines.cfg and guest-os.cfg from the backend-specific configuration directory. These files are located using data_dir.get_backend_cfg_path() based on the current vt.type setting (e.g., qemu or libvirt). The Cartesian parser processes these files to enumerate all valid guest and machine combinations.

How does the plugin determine if a guest image is available?

For each parsed guest definition, the plugin calls storage.get_image_filename() to resolve the absolute path to the disk image. It then checks os.path.isfile(image_name) to verify physical existence on the filesystem. If the file is missing, the output appends a warning message containing the expected filename.

Can I filter the guest list by architecture or machine type?

Yes. The get_guest_name_parser() function applies filters for vt.common.arch and vt.common.machine_type during the parsing phase. Additionally, you can use the --guest-os CLI option to restrict results to specific operating system names, such as fedora30 or centos7.

Where is the core guest listing logic implemented?

The primary implementation resides in avocado_vt/loader.py within the guest_listing() function. This function receives a configured Cartesian parser from virttest/standalone_test.py and handles the iteration, image verification, and formatted output generation that appears in the terminal.

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