Table of Contents

QEMU Guest Agent for Custom ISO Installations

When you install an operating system from a custom ISO, you also need to install QEMU Guest Agent inside the OS. This is a small service that allows the management platform to communicate with your server.

Why Is It Required?

Without QEMU Guest Agent, several features in your client portal will be unavailable or unreliable:

Feature Without QEMU Guest Agent
Private IP address display in client portal Not visible
Graceful shutdown and reboot Graceful shutdown/reboot work via ACPI; the guest agent adds agent-based control
Consistent backups Filesystem may not be properly frozen
Password reset from client portal Requires the guest agent
SSH key management from client portal Requires the guest agent

Servers created from pre-installed OS templates already have QEMU Guest Agent installed. You only need to install it manually if you used a custom ISO.

Installation on Linux

Debian / Ubuntu:

apt update && apt install -y qemu-guest-agent
systemctl enable --now qemu-guest-agent

AlmaLinux / Rocky Linux / CentOS / RHEL:

dnf install -y qemu-guest-agent
systemctl enable --now qemu-guest-agent

To verify the agent is running:

systemctl status qemu-guest-agent

Installation on Windows

The Windows installation requires the VirtIO Windows Guest Tools ISO, which is already available in your VDC as a pre-uploaded ISO. You do not need to download it from the internet.

  1. Open your server in the client portal and open the ISO / CD-ROM card on the server’s Overview tab
  2. Select “VirtIO Drivers for Windows (ISO)” from the dropdown and click Mount Only (no reboot needed)
  3. Inside Windows, open File Explorer and find the new CD-ROM drive containing virtio-win files
  4. Run virtio-win-gt-x64.msi – this installs all VirtIO drivers and QEMU Guest Agent at once
  5. Open Services (run services.msc) and verify that QEMU Guest Agent service is running with Startup Type set to Automatic
  6. After installation, open the ISO / CD-ROM card again to unmount the VirtIO ISO when you no longer need it

Tip: if you only need the agent without other drivers, run guest-agent\qemu-ga-x86_64.msi from the same CD-ROM drive.

Troubleshooting

Problem Solution
Private IP address is not showing in client portal Verify the agent is installed and running, then reboot the server
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 Startup Type to Automatic and click Start
Cannot find VirtIO ISO inside Windows Open the ISO / CD-ROM card on the server’s Overview tab, mount “VirtIO Drivers for Windows (ISO)”, then check File Explorer for the new CD-ROM drive