Skip to content

Conversation

@kallioli
Copy link

This PR adds the ability to install the QEMU Guest Agent directly from a VirtIO ISO file instead of always downloading from the internet.

⚠️ Note: This PR depends on #413 (QEMU GA checksum verification) and should be merged after it.

New Features

  • New source parameter with three options:
    • web: Download from internet (default, backward compatible)
    • iso: Extract from VirtIO ISO only
    • auto: Try ISO first, fallback to web
  • New Copy-QemuGuestAgentFromISO function for ISO extraction
  • Automatic architecture detection (x86_64/i386)
  • Comprehensive search with fallback paths and recursive search

Configuration Examples

Offline Mode

[drivers]
virtio_iso_path=/path/to/virtio-win.iso
 
[custom]
install_qemu_ga=True
 
[virtio_qemu_guest_agent]
source=iso
Automatic Mode (Recommended)
ini
[drivers]
virtio_iso_path=/path/to/virtio-win.iso
[custom]
install_qemu_ga=True
[virtio_qemu_guest_agent]
source=auto

Benefits

  • Offline environments: Support for air-gapped systems
  • Faster builds: No network download required
  • Version consistency: Match guest agent with VirtIO drivers version
  • Bandwidth savings: Reuse ISO for multiple image builds
  • Flexibility: auto mode works both online and offline

Technical Details

  • Mounts ISO using Windows VirtualDisk API
  • Searches multiple possible paths for the MSI file
  • Includes recursive search as fallback
  • Safe ISO dismount with cleanup
  • Backward Compatibility
  • All existing configurations continue to work without modification. The default source=web maintains current behavior.

Files Modified

Config.psm1
WinImageBuilder.psm1
Examples/windows-image-config-example.ini
README.md

Kevin Allioli added 2 commits December 11, 2025 17:49
* Add new [virtio_qemu_guest_agent] configuration section with url and checksum options
* Implement SHA256 checksum verification in Download-QemuGuestAgent function
* Update documentation with QEMU Guest Agent configuration examples and checksum usage
* Maintain full backward compatibility with existing configurations
* Add 'source' parameter to choose between ISO, web, or auto mode
* Implement Copy-QemuGuestAgentFromISO function for ISO extraction
* Support architecture mapping (x86_64/i386) for ISO file naming
* Add comprehensive search with fallback paths and recursive search
* Integrate source selection logic into Download-QemuGuestAgent
* Update documentation with ISO installation examples
* Maintain full backward compatibility with existing configurations

This feature enables offline installation and version consistency
by extracting QEMU Guest Agent directly from VirtIO ISO.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant