Custom ISO Images: QEMU Guest Agent Requirement
When using your own ISO image in Cloud VDC, it is required to install the QEMU Guest Agent inside the guest operating system after installation. Without it, several platform features will not work correctly.
Why Is It Required?
QEMU Guest Agent provides communication between your virtual machine and the management platform. Without it, the following features will be unavailable or unreliable:
| Feature | Without QEMU Guest Agent |
|---|---|
| IP address display in control panel | Not visible |
| Graceful shutdown / reboot | Only forced stop available |
| Consistent backups | Filesystem may not be properly frozen |
| Password reset from panel | Not available |
Installation on Linux
Debian / Ubuntu:
apt update && apt install -y qemu-guest-agent
systemctl enable --now qemu-guest-agentCentOS / RHEL / AlmaLinux:
yum install -y qemu-guest-agent
systemctl enable --now qemu-guest-agentTo verify the agent is running:
systemctl status qemu-guest-agentInstallation on Windows
Step 1. Download the VirtIO Windows Guest Tools ISO:
Step 2. Mount the ISO inside the virtual machine as a CD/DVD drive.
Step 3. Open the mounted drive in File Explorer and run virtio-win-gt-x64.msi — this will install all necessary drivers and QEMU Guest Agent.
Step 4. Open Services (services.msc) and verify that the QEMU Guest Agent VSS Provider service is running with Startup Type set to Automatic.
If you only need the agent without additional drivers, run guest-agent\qemu-ga-x86_64.msi from the same drive.
Troubleshooting
| Problem | Solution |
|---|---|
| IP address not showing in panel | Verify the agent is installed and running, then reboot the VM |
| Agent installed but not starting (Linux) | Run: systemctl enable --now qemu-guest-agent |
| Agent installed but not starting (Windows) | Open services.msc, find QEMU Guest Agent, set to Automatic and Start |
| Cannot find virtio-win.iso inside VM | Mount the ISO as CD/DVD drive from your control panel, then check File Explorer |