cloudbase · kallioli · Dec 11, 2025 · Dec 11, 2025
diff --git a/Config.psm1 b/Config.psm1
@@ -115,12 +115,22 @@ function Get-AvailableConfigOptions {
         @{"Name" = "install_qemu_ga"; "GroupName" = "custom";"DefaultValue" = "False";
           "Description" = "Installs QEMU guest agent services from the Fedora VirtIO website.
                            Defaults to 'False' (no installation will be performed).
-                           If set to 'True', the following MSI installer will be downloaded and installed:
+                           If set to 'True', by default, the following MSI installer will be downloaded and installed:
                              * for x86: https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/archive-qemu-ga/qemu-ga-win-100.0.0.0-3.el7ev/qemu-ga-x86.msi
                              * for x64: https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/archive-qemu-ga/qemu-ga-win-100.0.0.0-3.el7ev/qemu-ga-x64.msi
                            The value can be changed to a custom URL, to allow other QEMU guest agent versions to be installed.
                            Note: QEMU guest agent requires VirtIO drivers to be present on the image.
                           "},
+        @{"Name" = "source"; "GroupName" = "virtio_qemu_guest_agent"; "DefaultValue" = "web";
+          "Description" = "Source for QEMU Guest Agent installation. Options:
+                           'iso' - Extract from VirtIO ISO (requires virtio_iso_path to be set),
+                           'web' - Download from Internet (default behavior),
+                           'auto' - Try ISO first, fallback to web if extraction fails.
+                           Default: 'web'"},
+        @{"Name" = "url"; "GroupName" = "virtio_qemu_guest_agent";
+          "Description" = "Custom URL for QEMU Guest Agent MSI installer. Must be used together with 'checksum' parameter for SHA256 verification."},
+        @{"Name" = "checksum"; "GroupName" = "virtio_qemu_guest_agent";
+          "Description" = "SHA256 checksum of the QEMU Guest Agent MSI installer. Must be used together with 'url' parameter."},
         @{"Name" = "drivers_path"; "GroupName" = "drivers";
           "Description" = "The location where additional drivers that are needed for the image are located."},
         @{"Name" = "install_updates"; "GroupName" = "updates"; "DefaultValue" = $false; "AsBoolean" = $true;

diff --git a/Examples/windows-image-config-example.ini b/Examples/windows-image-config-example.ini
@@ -142,6 +142,25 @@ drivers_path=""
 # The value can be changed to a custom URL, to allow other QEMU guest agent versions to be installed.
 # Note: QEMU guest agent requires VirtIO drivers to be present on the image.
 install_qemu_ga=False
+
+[virtio_qemu_guest_agent]
+# Source for QEMU Guest Agent installation. Options:
+# - 'iso': Extract from VirtIO ISO (requires virtio_iso_path to be set)
+# - 'web': Download from Internet (default behavior)
+# - 'auto': Try ISO first, fallback to web if extraction fails
+# Default: 'web'
+source=web
+# Custom URL for QEMU Guest Agent MSI installer.
+# Must be used together with 'checksum' parameter for SHA256 verification.
+# Example: url=https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/archive-qemu-ga/qemu-ga-win-VERSION/qemu-ga-x64.msi
+url=
+# SHA256 checksum of the QEMU Guest Agent MSI installer.
+# Must be used together with 'url' parameter.
+# To get the checksum on Windows: Get-FileHash -Path "qemu-ga-x64.msi" -Algorithm SHA256
+# To get the checksum on Linux/macOS: sha256sum qemu-ga-x64.msi
+checksum=
+
+[custom]
 # Set a custom timezone for the Windows image.
 time_zone=""
 # Set custom ntp servers(space separated) for the Windows image

diff --git a/README.md b/README.md
@@ -94,6 +94,173 @@ the resulting VHDX is shrinked to a minimum size and converted to the required f
 You can find a PowerShell example to generate a raw OpenStack Ironic image that also works on KVM<br/>
 in `Examples/create-windows-online-cloud-image.ps1`
 
+## QEMU Guest Agent Configuration
+
+### Overview
+
+The QEMU Guest Agent installation supports multiple configuration modes:
+
+- **Source selection**: Install from VirtIO ISO, web download, or automatic fallback
+- **Checksum verification**: Optional SHA256 verification for enhanced security
+- **Full backward compatibility**: All existing configurations continue to work
+
+### Installation Source Options
+
+The `source` parameter in the `[virtio_qemu_guest_agent]` section controls where the QEMU Guest Agent is obtained from:
+
+| Value | Description | Requires VirtIO ISO | Behavior |
+|-------|-------------|---------------------|----------|
+| `web` | Download from internet (default) | No | Downloads from fedorapeople.org |
+| `iso` | Extract from VirtIO ISO only | **Yes** | Fails if ISO not available or MSI not found |
+| `auto` | Try ISO first, fallback to web | No | Intelligent: uses ISO if available, otherwise downloads |
+
+### Configuration Examples
+
+#### 1. Default Installation (Simple)
+
+```ini
+[custom]
+install_qemu_ga=True
+```
+
+Uses the default version from the VirtIO archive (web download).
+
+#### 2. Extract from VirtIO ISO (Offline Mode)
+
+```ini
+[drivers]
+virtio_iso_path=/path/to/virtio-win.iso
+
+[custom]
+install_qemu_ga=True
+
+[virtio_qemu_guest_agent]
+source=iso
+```
+
+Extracts the QEMU Guest Agent from the VirtIO ISO. Useful for offline environments.
+
+#### 3. Automatic Mode (Recommended)
+
+```ini
+[drivers]
+virtio_iso_path=/path/to/virtio-win.iso
+
+[custom]
+install_qemu_ga=True
+
+[virtio_qemu_guest_agent]
+source=auto
+```
+
+Tries ISO extraction first, automatically falls back to web download if needed.
+
+#### 4. Secure Installation with Checksum
+
+```ini
+[custom]
+install_qemu_ga=True
+
+[virtio_qemu_guest_agent]
+source=web
+url=https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/archive-qemu-ga/qemu-ga-win-VERSION/qemu-ga-x64.msi
+checksum=<SHA256_CHECKSUM>
+```
+
+Downloads from a custom URL with SHA256 checksum verification. Both `url` and `checksum` must be specified together.
+
+#### 5. Legacy Custom URL
+
+```ini
+[custom]
+install_qemu_ga=https://example.com/custom-qemu-ga.msi
+```
+
+Downloads from a custom URL without checksum verification (backward compatibility).
+
+### Priority Order
+
+The system follows this priority order:
+
+1. **Custom URL + Checksum** (if both provided) → Always used, `source` is ignored
+2. **Source-based installation**:
+   - `source=iso` → Extract from ISO only (error if fails)
+   - `source=auto` → Try ISO, fallback to web
+   - `source=web` → Download from internet
+3. **Legacy behavior** (backward compatibility):
+   - `install_qemu_ga=True` → Default URL
+   - `install_qemu_ga=<URL>` → Custom URL without checksum
+
+### VirtIO ISO Structure
+
+When using `source=iso` or `source=auto`, the system searches for the QEMU Guest Agent MSI in these locations:
+
+- `guest-agent/qemu-ga-x86_64.msi` (for 64-bit) ✓ **Most common**
+- `guest-agent/qemu-ga-i386.msi` (for 32-bit) ✓ **Most common**
+- `guest-agent/qemu-ga-x64.msi` (alternative naming)
+- `guest-agent/qemu-ga-x86.msi` (alternative naming)
+- Additional fallback paths and recursive search
+
+The system automatically detects and uses the correct MSI file based on the image architecture.
+
+### Getting the SHA256 Checksum
+
+**Windows (PowerShell)**:
+```powershell
+Get-FileHash -Path "qemu-ga-x64.msi" -Algorithm SHA256
+```
+
+**Linux/macOS**:
+```bash
+sha256sum qemu-ga-x64.msi
+```
+
+### Benefits
+
+- **Offline environments**: Use `source=iso` for air-gapped systems
+- **Faster builds**: Avoid network downloads with local ISO
+- **Version consistency**: Match guest agent with VirtIO drivers version
+- **Security**: SHA256 checksum verification prevents tampering
+- **Flexibility**: `source=auto` works both online and offline
+- **Bandwidth savings**: Reuse ISO for multiple image builds
+
+### Best Practices
+
+1. **Use `source=auto` for flexibility**: Works both online and offline
+2. **Use `source=iso` for strict offline environments**: Ensures no internet access is attempted
+3. **Use `source=web` with checksum**: For maximum security when downloading
+4. **Match versions**: Keep guest agent version consistent with VirtIO drivers
+
+### Technical Details
+
+**ISO Mounting Process**:
+1. Creates a temporary backup copy of the ISO
+2. Mounts the ISO using Windows VirtualDisk API
+3. Searches for the QEMU Guest Agent MSI
+4. Copies the MSI to the resources directory
+5. Safely dismounts and cleans up the temporary ISO
+
+**Architecture Mapping**:
+
+| Windows Architecture | ISO Filename |
+|---------------------|--------------|
+| AMD64 (64-bit) | `qemu-ga-x86_64.msi` |
+| x86 (32-bit) | `qemu-ga-i386.msi` |
+
+### Troubleshooting
+
+**Q: The build fails with "QEMU Guest Agent MSI not found in VirtIO ISO"**
+
+A: Your VirtIO ISO might have a different structure. Use `source=auto` to fall back to web download, or `source=web` to skip ISO extraction entirely.
+
+**Q: I want to force internet download even though I have an ISO**
+
+A: Set `source=web` in the configuration.
+
+**Q: How do I ensure version consistency between VirtIO drivers and guest agent?**
+
+A: Use `source=iso` to extract the guest agent from the same VirtIO ISO used for drivers.
+
 ## Frequently Asked Questions (FAQ)
 
 ### The image generation never stops