QEMU Guest Agent

Overview

The QEMU Guest Agent (qemu-ga) is an in-guest service that lets Private Cloud Director coordinate with the guest operating system running inside a VM. With the agent installed, enabled, and reachable, PCD can:

• Quiesce filesystems during snapshots, so a live snapshot is filesystem-consistent instead of merely crash-consistent. On Windows, this uses Volume Shadow Copy Service (VSS) for application-consistent snapshots.
• Set the administrator password of a running VM through the platform, without needing network access into the guest.
• Sync the guest clock after operations that pause the guest, such as a hard reboot, resume, or cold migration. This happens automatically on a best-effort basis once the agent is installed and running. There is no setting to configure and no command to trigger it.

What the guest agent does not do today:

• PCD does not expose agent-reported guest data (OS version, IP addresses) through its API.
• PCD does not use the guest agent for VM health monitoring.
• PCD does not install the guest agent into guests automatically; you install and enable it yourself, as described on this page.
• There is no memory ballooning or page sharing associated with the guest agent. It is not a full VMware Tools replacement, though it covers the most commonly used capabilities: consistent snapshots, password reset, and clock sync.

The guest agent is qualified across 13 guest operating systems on PCD: Ubuntu 20.04, 22.04, and 24.04; Debian 12; Rocky Linux 8.10, 9.8, and 10.2; AlmaLinux 9.8; Windows Server 2016, 2019, 2022, and 2025; and Windows 11 Enterprise 24H2.

Guest OS	Guest agent version	How the agent gets there
Ubuntu 20.04.6	qemu-ga 4.2.1	Install required (apt)
Ubuntu 22.04.5	qemu-ga 6.2	Install required (apt)
Ubuntu 24.04.4	qemu-ga 8.2	Install required (apt)
Debian 12	qemu-ga 7.2	Install required (apt)
Rocky Linux 8.10	qemu-ga 6.2	Pre-shipped in the GenericCloud image
Rocky Linux 9.8	qemu-ga 10.1	Pre-shipped in the GenericCloud image
Rocky Linux 10.2	qemu-ga 10.1	Pre-shipped in the GenericCloud image
AlmaLinux 9.8	qemu-ga 10.x	Pre-shipped in the GenericCloud image
Windows Server 2016	qemu-ga 110.0.2	virtio-win guest tools (virtio-win 0.1.285)
Windows Server 2019	qemu-ga 110.0.2	virtio-win guest tools (virtio-win 0.1.285)
Windows Server 2022	qemu-ga 110.0.2	virtio-win guest tools (virtio-win 0.1.285)
Windows Server 2025	qemu-ga 110.0.2	virtio-win guest tools (virtio-win 0.1.285)
Windows 11 Enterprise 24H2	qemu-ga 110.0.2	virtio-win guest tools (virtio-win 0.1.285)

For the Linux guests, cloud images in the Debian family (Ubuntu, Debian) do not ship the agent, so you install it yourself. RHEL-family cloud images (Rocky Linux, AlmaLinux) already ship the agent in the GenericCloud image; you only need to enable it. All five Windows editions install the agent from the virtio-win guest tools, alongside the QEMU Guest Agent VSS Provider that Windows needs for application-consistent snapshots.

In this guide, you will enable the guest agent on an image, install it in each supported guest OS family, verify it is working, and understand the consistency and security behavior you should plan around.

Enable the Guest Agent on an Image

The guest agent is enabled through image properties. There is no VM flavor equivalent and no dedicated UI checkbox, but you can set the properties as key-value pairs from the UI.

Property	Effect
hw_qemu_guest_agent=yes	Adds the virtio-serial channel device the guest agent needs. Without it, the agent service inside the guest cannot start.
os_require_quiesce=yes	Makes snapshot operations require a successful filesystem freeze instead of a best-effort one. Read Understand Snapshot Consistency Behavior before relying on this for backups.

To set both properties from the UI:

1. Navigate to Virtual Machines in the left-hand navigation menu, then go to Images & VM Snapshots > Images.
2. Select the image and click Edit Properties.
3. Add hw_qemu_guest_agent with the value yes, and os_require_quiesce with the value yes.
4. Click Update Properties.
5. Reopen Edit Properties to confirm both names and values were saved exactly as entered.

The equivalent pcdctl commands are:

pcdctl image set <image> --property hw_qemu_guest_agent=yes --property os_require_quiesce=yes
pcdctl image show <image>

Set Image Properties Before Booting a VM

Image properties are copied into each VM at creation time, and this has a practical consequence: adding hw_qemu_guest_agent=yes to an image later does not affect VMs that were created from it before the change. This holds across reboot (soft or hard), stop and start, resize, migrate, and shelve.

The only operation that picks up a property added after creation is rebuild. To rebuild from the UI, select the VM in the VM grid view, choose Rebuild from the Actions menu, and select the image to rebuild from. See Virtual Machine Actions for what a rebuild preserves.

The equivalent pcdctl command is:

pcdctl server rebuild <instance> <same-or-new-image>

Rebuild is disruptive: the instance reboots and its ephemeral disk is reset to the image contents. Plan and schedule it rather than running it against a production fleet without notice. One exception applies: a Windows guest built with a vTPM (secure boot) cannot be rebuilt at all. Such guests must be redeployed rather than retrofitted.

The same rule applies to os_require_quiesce, including on boot-from-volume VMs. The property must be present on the image or the boot volume at boot time. Setting it on a boot volume after the instance has already booted does not retrofit that instance; its snapshots continue to quiesce best-effort rather than enforced, with no error to indicate the property had no effect.

Install the Guest Agent

Enable the two image properties above before you boot the VM, then follow the steps for your guest OS family.

Debian-family: Ubuntu and Debian

Applies to Ubuntu 20.04, 22.04, 24.04, and Debian 12. The cloud images for these distributions do not ship the guest agent, so you install it explicitly.

1. Confirm the instance was created from an image with hw_qemu_guest_agent=yes set. If the property was missing at boot, the agent service cannot start regardless of whether the package is installed (see the failure mode in step 4).
2. Install the guest agent package:

   sudo apt-get install -y qemu-guest-agent

3. Enable and start the service:

   sudo systemctl enable --now qemu-guest-agent

4. Verify the installation:

   systemctl is-active qemu-guest-agent
   ls -l /dev/virtio-ports/org.qemu.guest_agent.0

   systemctl is-active should report active, and the device file should exist.

   If the service instead fails with Dependency failed for QEMU Guest Agent, the image was missing hw_qemu_guest_agent=yes when the instance was created; the unit binds to a virtio channel device that does not exist without that property. This is a missing image property, not a broken package installation. On newer Debian releases the same underlying cause shows up as a quieter single "Dependency failed" line instead of a timeout.

Debian-family guests ship with the agent's full command surface open by default. If your operator and tenant are different trust domains, follow the hardening steps in Secure the Guest Agent after installation.

RHEL-family: Rocky Linux and AlmaLinux

Applies to Rocky Linux 8.10, 9.8, 10.2, and AlmaLinux 9.8. The GenericCloud images for these distributions already ship the guest agent, so there is nothing to install, only to enable.

1. Confirm the instance was created from an image with hw_qemu_guest_agent=yes set.
2. Enable and start the service:

   sudo systemctl enable --now qemu-guest-agent

3. Verify the installation the same way as Debian-family:

   systemctl is-active qemu-guest-agent
   ls -l /dev/virtio-ports/org.qemu.guest_agent.0

4. No further hardening step is required to reach a safe default. The default configuration already restricts the command surface: guest-exec and the guest-file-* commands are blocked, while filesystem quiescing and the admin password reset both work out of the box. See Secure the Guest Agent for the details of what is and isn't allowed by default.

Windows: Windows Server and Windows 11

Applies to Windows Server 2016, 2019, 2022, 2025, and Windows 11 Enterprise 24H2. The agent and its VSS provider install together from the virtio-win guest tools.

1. Build or edit the image with hw_qemu_guest_agent=yes present before the first boot. Without it, the agent can never connect, no matter what you install inside the guest.
2. Attach the virtio-win ISO inside the guest and run the guest tools installer:

   virtio-win-guest-tools.exe

   Alternatively, install virtio-win-gt-x64.msi directly. Either installs both the QEMU Guest Agent and the QEMU Guest Agent VSS Provider.
3. Confirm all three services required for application-consistent snapshots are present and correctly configured:

   • QEMU Guest Agent: running, Automatic start
   • QEMU Guest Agent VSS Provider: Manual (on-demand) start
   • Volume Shadow Copy: Manual (on-demand) start
4. Verify with PowerShell:

   Get-Service QEMU-GA,"QEMU Guest Agent VSS Provider",VSS

If an unattended installation loads storage drivers during Windows setup, point it at the driver directory for your version. virtio-win 0.1.285 ships all of the following:

Windows version	Driver directory
Windows Server 2016	viostor\2k16\amd64 and vioscsi\2k16\amd64
Windows Server 2019	2k19
Windows Server 2022	2k22
Windows Server 2025	2k25
Windows 11	w11

Windows Server 2016 setup requires the narrowed driver paths above. A broad autounattend DriverPaths entry that recursively scans a drive root fails setup with could not install one or more boot-critical drivers. Later Windows Server versions tolerate the broad form.

Windows 11 (client) needs a 64 GB disk, plus vTPM 2.0 and Secure Boot enabled, to satisfy the Windows 11 hardware check. Also set the os_admin_user image property on client Windows images to an enabled local admin account: the built-in Administrator account is disabled by default on client editions, which affects password reset (see Set the Administrator Password via the Guest Agent).

Windows guests ship with the agent's full command surface open by default, the same as Debian-family. See Secure the Guest Agent if you need to restrict it.

Verify the Guest Agent Is Working

From inside the guest:

• Linux: ls -l /dev/virtio-ports/org.qemu.guest_agent.0 shows the device, and systemctl is-active qemu-guest-agent reports active.
• Windows: the three services listed above are present, and the QEMU Guest Agent service is running.

From the platform side, a snapshot of the VM completes, and with os_require_quiesce=yes the agent logs a freeze and thaw around the snapshot: in the Linux guest journal, or as VSS provider and Volume Shadow Copy service activity in the Windows event log.

If you are checking freeze and thaw directly with agent commands, note that both return the number of filesystems processed, for example {"return": 2}. There is no THAWED string in the response.

Two Windows expectation-setting notes:

• The frozen-filesystem count varies by Windows build, not by your partition layout. Windows Server 2016 freezes 1 filesystem; Windows Server 2019 and 2022 freeze 2 on an identical partition layout; Windows Server 2025 and Windows 11 freeze 3 (the third being the WinRE Recovery partition that Windows Setup creates automatically). All of these counts are normal.
• Client Windows 11 does not log the 7036 service-state events that Windows Server logs during a freeze. Don't rely on the event log to confirm VSS engagement on Windows 11; check service state directly with Get-Service during the freeze window instead.

Set the Administrator Password via the Guest Agent

There is no UI action for this today. Set the password of a running VM through the agent with pcdctl:

pcdctl server set --password <new-password> <vm-name-or-id>

This requires hw_qemu_guest_agent=yes and a running, responsive agent. Failure modes are clean, and the VM stays running either way:

• A missing image property returns HTTP 409.
• An unresponsive agent returns HTTP 501.

The target account is root on Linux or Administrator on Windows, unless the image sets the os_admin_user property to a different account. This works out of the box on every validated Linux guest, including the RHEL family, because the default agent configuration allows the password-set command even while it blocks broader command execution.

Client Windows trap: on client editions such as Windows 11, the built-in Administrator account is disabled by default, unlike Windows Server. Setting a password against the default account still reports success (the agent genuinely sets the password), but nobody can log in with it until the account is enabled. On client Windows images, set the os_admin_user image property to a local admin account that is already enabled.

Understand Snapshot Consistency Behavior

A few storage and lifecycle behaviors are worth knowing before you build a backup procedure around quiesced snapshots:

• Stopped VMs snapshot without quiesce. There is nothing to freeze, so this is expected and safe.
• Guest-initiated shutdowns can take up to 10 minutes to be reflected in PCD. The platform reconciles guest-initiated power changes on a periodic sweep; the fast event path applies mostly to VM starts, not shutdowns. Give a guest-initiated shutdown time to be reflected before acting on the status you see, and always start instances through the PCD API or UI rather than from outside the platform. A VM started outside the platform can be shut off again automatically the next time the platform reconciles state.

Configure Application-Consistent Snapshots on Linux

Quiescing a Linux guest freezes its filesystems. That flushes the operating system's cached writes and leaves the filesystem clean, but it does not reach into running applications: a database with an open transaction holds data in its own memory that the freeze never sees. The result is a filesystem-consistent snapshot, not an application-consistent one.

To close that gap, the guest agent can run a hook script immediately before it freezes the filesystems and again after it thaws them. That hook is where you tell your application to flush and pause. You write the script; every distribution then runs it the same way.

1. Write the Hook Script

The agent runs your script twice: once with the argument freeze before the filesystems are frozen, and once with thaw after they are released. Handle both. This example puts PostgreSQL into backup mode for the duration of the freeze:

#!/bin/sh
# 10-postgres.sh
case "$1" in
  freeze) su - postgres -c "psql -c \"SELECT pg_backup_start('snapshot');\"" ;;
  thaw)   su - postgres -c "psql -c \"SELECT pg_backup_stop();\"" ;;
esac

Adapt the two commands to your application: a MySQL hook would use FLUSH TABLES WITH READ LOCK and UNLOCK TABLES, while an application without a quiesce mode might stop and start its service. The freeze and thaw structure stays the same. Make the script executable with chmod +x.

pg_backup_start() and pg_backup_stop() are PostgreSQL 15 and later. On PostgreSQL 14 and earlier the equivalents are pg_start_backup() and pg_stop_backup(). Check which version your distribution ships: Ubuntu 22.04 defaults to PostgreSQL 14, Debian 12 to 15, and Ubuntu 24.04 to 16.

Keep hook scripts fast and non-blocking. The filesystem stays frozen for as long as the hook runs, and writes from the rest of the guest block for that entire window. A hook that hangs will hold the guest's filesystems frozen.

2. Install the Hook

Where the script goes, and whether any setup is needed first, depends on the distribution.

Rocky Linux and AlmaLinux have the hook wired up already. Place your script in /etc/qemu-ga/fsfreeze-hook.d/ and it takes effect on the next snapshot. Nothing else is required. That directory is empty by default, which is why snapshots are filesystem-consistent until you add a script to it.

Ubuntu and Debian do not run a hook by default. Enable it once, then add scripts the same way.

Create the hook dispatcher at /etc/qemu/fsfreeze-hook, which runs everything in its companion directory:

sudo mkdir -p /etc/qemu/fsfreeze-hook.d
sudo tee /etc/qemu/fsfreeze-hook >/dev/null <<'EOF'
#!/bin/sh
# Runs every executable in fsfreeze-hook.d/, passing through "freeze" or "thaw".
for hook in /etc/qemu/fsfreeze-hook.d/*; do
    [ -x "$hook" ] || continue
    "$hook" "$@"
done
EOF
sudo chmod +x /etc/qemu/fsfreeze-hook

Point the agent at it with a systemd drop-in. The empty ExecStart= line is required, because it clears the packaged one before the replacement is applied:

sudo systemctl edit qemu-guest-agent

[Service]
ExecStart=
ExecStart=-/usr/sbin/qemu-ga -F/etc/qemu/fsfreeze-hook

Restart the agent:

sudo systemctl daemon-reload
sudo systemctl restart qemu-guest-agent

Your script then goes in /etc/qemu/fsfreeze-hook.d/ and behaves exactly as it does on Rocky Linux and AlmaLinux.

3. Verify the Hook Fires

Take a snapshot with os_require_quiesce=yes and check the guest journal:

sudo journalctl -u qemu-guest-agent --since "5 min ago"

A working hook logs the freeze and thaw hook entries alongside guest-fsfreeze called. If you see the freeze but no hook entries, the hook is not enabled or the script is not executable.

Migrate, Evacuate, and Use High Availability

The guest agent channel is a per-instance host socket, so it is reasonable to ask whether it survives a VM moving between hosts. It does: the channel remains connected, and the agent responds on the destination host, after a live migration, a cold migration, and an evacuation from a failed host. This includes Windows secure-boot VMs, with one prerequisite.

• Secure-boot Windows VMs (vTPM) cannot be live-migrated with default flavor settings. A VM with a virtual TPM refuses live migration unless its flavor carries the extra spec hw:tpm_secret_security=host. With that flavor setting, live migration succeeds and both the agent channel and the vTPM survive the move. This must be chosen when the VM is first created: it cannot be changed on a running VM, and vTPM VMs cannot be rebuilt. If you run secure-boot Windows guests that may need live migration, define and use a flavor with hw:tpm_secret_security=host from the start. See Virtual TPM for more on vTPM-enabled VMs.
• Do not migrate a VM during an active backup freeze. A filesystem freeze in progress is not thawed by a migration; a guest migrated mid-freeze arrives on the destination still frozen.
• VM High Availability does not react to a guest-initiated shutdown, because it monitors host health, not individual VM power state. A VM shut down from inside the guest stays down until you start it again.

Secure the Guest Agent

The guest agent is a host-to-guest command channel, and it is part of your trust boundary. Its default posture differs sharply by guest OS family.

• RHEL-family guests (Rocky Linux, AlmaLinux) restrict the agent by default, though the exact mechanism differs by generation. On Rocky Linux 8-class guests, it's a block list: everything not explicitly named is permitted. On Rocky Linux 9 and later (including AlmaLinux 9), it's an allow list: everything not explicitly named is denied, which is the stronger posture. In both generations, guest-exec and the guest-file-* commands are blocked by default, while the password-set and filesystem-freeze commands are allowed, so password reset and quiesced snapshots work out of the box without exposing host-driven command execution. Allowed commands on Rocky Linux 8-class guests also run confined under SELinux.

  One quirk to know about: on Rocky Linux 8, the agent reports a blocked command with the misleading text "the agent is in frozen state". That message does not mean the filesystem is actually frozen; it means the command was blocked by the agent's configuration.
• Debian-family (Debian, Ubuntu) and Windows guests block nothing by default. The allowed commands run as root (Linux) or SYSTEM (Windows), unconfined. This means anything with access to the guest agent socket on the host side can run arbitrary commands and read or write arbitrary files inside the guest. If that is broader access than your tenancy model allows, restrict it.

  Debian-family guests have no /etc/sysconfig/qemu-ga, so add the blocked commands to the service's launch options with a systemd drop-in:

  sudo systemctl edit qemu-guest-agent

  In the drop-in, clear the inherited ExecStart and restate it with the block list appended. Mirror the binary path and any existing options from the unit's own ExecStart, which you can read with systemctl cat qemu-guest-agent:

  [Service]
  ExecStart=
  ExecStart=-/usr/sbin/qemu-ga --block-rpcs=guest-exec,guest-exec-status,guest-file-open,guest-file-read,guest-file-write

  If you also enable the freeze hook described in Configure Application-Consistent Snapshots on Linux, put both options on a single ExecStart line rather than creating a second drop-in, since systemctl edit writes to the same override file.

  Then reload and restart the service:

  sudo systemctl daemon-reload
  sudo systemctl restart qemu-guest-agent

Recommendation: enable the guest agent for its snapshot and password-reset functions on every guest. On Debian-family images, explicitly block guest-exec* and guest-file-* unless the cloud operator and the guest tenant are the same trust domain. RHEL-family images are already restricted by default; only unblock guest-exec there if you specifically need host-driven command execution inside the guest.

Troubleshoot the Guest Agent

Symptom	Cause	Fix
Dependency failed for QEMU Guest Agent in the guest; no /dev/virtio-ports/* device	The image lacked hw_qemu_guest_agent=yes when the instance was created	Set the property on the image, then rebuild the instance (a reboot is not enough)
Property is set on the image, but an existing VM still has no channel	Image properties are frozen into each instance at creation time	Rebuild the instance
Boot-from-volume snapshot fails with HTTP 409, "Failed to quiesce"	os_require_quiesce=yes is set and the agent is enabled but not responding	Start the agent, or remove the property to accept crash-consistent snapshots. This is the correct, safe failure behavior.
Boot-from-volume snapshot fails with HTTP 400	os_require_quiesce=yes is set, but the image or volume never had hw_qemu_guest_agent=yes at boot	Set the property before boot, or rebuild the instance
pcdctl server set --password returns HTTP 501	The agent is enabled but not running or responding inside the guest	Start the agent service inside the guest
pcdctl server set --password returns HTTP 409	The image lacks hw_qemu_guest_agent=yes at boot	Set the property, then rebuild
pcdctl server set --password succeeds on client Windows, but login fails	The built-in Administrator account is disabled by default on client editions; the password was set on a disabled account	Set os_admin_user on the image to an enabled local admin, or enable the Administrator account
Windows snapshot is not application-consistent	The VSS provider service is not running	Install and start the QEMU Guest Agent VSS Provider and Volume Shadow Copy services (both come from the virtio-win guest tools)
Windows required-quiesce snapshot fails with an HTTP 500 error	The QEMU Guest Agent VSS Provider service is stopped, so the in-guest freeze fails	Start the QEMU Guest Agent VSS Provider and Volume Shadow Copy services, then retry
Windows secure-boot VM refuses live migration ("not supported for vTPM-enabled instance")	The flavor uses the default TPM secret policy	Recreate the VM on a flavor with hw:tpm_secret_security=host (this cannot be changed on a running vTPM VM)

Known Limitations

• With os_require_quiesce=yes, a snapshot of an image-backed (ephemeral) VM whose guest agent is not responding (stopped, hung, or never installed) completes successfully as a crash-consistent snapshot, with no error returned. A boot-from-volume VM in the same state correctly fails the snapshot with HTTP 409. This is reproduced on all 13 validated guest operating systems. Until this is resolved, treat in-guest agent health as part of your backup procedure, or use boot-from-volume where the quiesce guarantee must be enforced.
• On Windows, if the QEMU Guest Agent VSS Provider service is stopped while the guest agent itself is healthy, a required-quiesce snapshot fails with a generic HTTP 500 error instead of a clean quiesce-failed error. This is reproduced on all five validated Windows editions. Confirm all three Windows services (QEMU Guest Agent, QEMU Guest Agent VSS Provider, Volume Shadow Copy) are running before relying on application-consistent snapshots.

Related Pages

• Virtual Machine Snapshot: how live snapshots work, and why they're crash-consistent without the guest agent
• Image Properties: full reference for hw_qemu_guest_agent, os_require_quiesce, and other image properties
• Create a Windows VM from an ISO: build a Windows golden image, including the properties this page depends on
• Virtual TPM: vTPM behavior and constraints for secure-boot Windows VMs