QEMU Guest Agent (Host-Guest communication service channel)

QEMU Guest Agent is a background service inside a virtual machine that allows the host to safely execute commands in the guest operating system. Simply put, it is a special helper through which the virtualization platform can politely ask the guest system to do something without network interference.

QEMU (Emulator and hardware virtualizer of a computer)

The technology is used in Proxmox VE, oVirt, OpenStack, and libvirt virtualization platforms to obtain IP addresses without network scanning, ensure consistent filesystem freezing during snapshot creation, inject SSH keys into cloud images, and precisely control guest memory usage. Administrators use the agent for trivial guest shutdown and sending custom scripts via the QMP protocol.

Typical problems

The most common malfunction is the absence of an installed agent in the virtual machine template, which causes backup to hang at the snapshot creation stage. A hung or outdated service inside the guest blocks fsfreeze commands, leading to data corruption. Problems are also caused by a damaged virtio-serial channel or the absence of the corresponding serial device. Sometimes the guest agent conflicts with cloud init-systems during parallel password configuration.

QEMU Guest Agent operating principle

The interaction is based on a simplex data transmission channel through a virtio-serial device, which emulates a direct serial port between the host and guest without hardware UART emulation. When the virtual machine starts, the hypervisor creates a special socket on the host, connected to the guest device /dev/virtio-ports/org.qemu.guest_agent.0. Inside the guest operating system, the qemu-guest-agent service runs, opens this character port, and enters a mode waiting for JSON commands according to the QMP specification. Unlike network synchronization protocols, data transmission here goes directly through shared memory of virtio ring buffers, guaranteeing delivery even in the absence of an emulated network.

The communication format is fully asynchronous. The host sends a JSON dictionary with execute and arguments fields, and after performing the operation, the agent returns a dictionary with a return field or an error. The key technical feature lies in processing the guest-fsfreeze-freeze command: the agent does not simply set filesystems to read-only mode but uses the Linux kernel FIFREEZE mechanism via the ioctl system call, which freezes dirty pages in the page cache and prohibits new writes at the VFS level until the guest-fsfreeze-thaw command is received. For memory coordination, the guest-get-memory-block-info command is used, querying the balloon driver kernel subsystem. In the case of a password request, the agent interacts with the guest PAM modules, setting the shadow file hash, bypassing interactive input. This achieves full control over the guest OS state without network dependency while maintaining data consistency on block devices during instant snapshots.

Functionality

  1. Protocol Synchronization. The guest-sync command. The function implements a strobing mechanism to restore the connection after failures. The host sends a counter value, the agent returns it back. This process allows the hypervisor to determine the serial port buffer state, synchronize data transmission, and guarantee processing of all pending responses before starting a new command exchange.
  2. State Monitoring. The guest-ping command. A simple agent availability check without performing modifying operations. The host sends an empty request and waits for a successful response. The command serves as a guest service health indicator and is used by virtualization platforms for periodic virtual machine state checks without loading their filesystem.
  3. Time Management. The guest-get-time and guest-set-time commands. Allows reading and adjusting the guest OS system clock from the host. The command returns time in nanoseconds relative to the Unix epoch. This is critically important during VM migration or after suspension, when time discrepancy between the host and guest can disrupt the operation of timing-sensitive applications, for example, databases.
  4. Shutdown. The guest-shutdown command. Performs a controlled shutdown of the guest system using the OS itself. The command emulates pressing the power button or executing a shutdown system call. Unlike forcibly killing the QEMU process, this method guarantees filesystem data preservation and correct termination of services inside the virtual machine.
  5. Suspend to Sleep Mode. The guest-suspend-* commands. A group of commands for transitioning the guest into various energy-saving modes. Suspend to RAM (S3), to disk (S4), and hybrid modes are supported. Execution success depends on guest kernel capabilities, systemd settings, and hardware specifics. The command returns a mode support flag in the guest-info response.
  6. Filesystem Access. The guest-file-open command. Opens a file inside the guest OS and returns an integer descriptor for further manipulations. Arguments include the full file path and an optional open mode in fopen notation. This command is intended for limited debug access, for example, reading logs, not for intensive I/O.
  7. File Data Reading. The guest-file-read command. Reads a block of data from a file opened via guest-file-open. The result is returned in base64 encoding for safe binary data transmission through JSON. The maximum size of readable data is limited to 48 MB. The command returns a read byte count, a data buffer, and an end-of-file flag.
  8. File Writing. The guest-file-write command. Writes data to a guest file, accepting content in base64 format. Arguments are an open file descriptor and an encoded string. The command returns the number of bytes actually written and an EOF status. Used for injecting configuration files or setup scripts during the VM initialization process.
  9. Offset Management. The guest-file-seek command. Changes the current read/write position in a file by its descriptor. Supports standard positioning mnemonics: from the file beginning, from the current position, and from the end. This function is necessary for working with large log files, allowing skipping headers or reading the last entries without transferring all the content.
  10. Buffer Flushing. The guest-file-flush command. Forcibly flushes all buffered data associated with a file descriptor to persistent storage. The command guarantees physical writing of data to disk, bypassing the guest OS cache. Used to ensure the integrity of critical information before creating a virtual machine snapshot.
  11. Command Execution. The guest-exec and guest-exec-status commands. Enables launching arbitrary executable files inside the guest with capturing stdout and stderr streams. guest-exec returns the process PID, while guest-exec-status allows monitoring its execution and obtaining the return code. The command output is encoded in base64. Provides full automation capability for external administration.
  12. Filesystem Freezing. The guest-fsfreeze-freeze and guest-fsfreeze-thaw commands. The freeze command suspends I/O operations on guest filesystems, ensuring a consistent state for creating storage snapshots. The thaw command restores operation. The function supports freezing by mount point list, which is critical for enterprise-level storage systems and prevents data corruption during backup.
  13. Storage Optimization. The guest-fstrim command. Informs the guest OS about unused filesystem blocks for returning them to the hypervisor (discard). The agent calls the fstrim system call, allowing reduction of the actual image file size in qcow2 or raw formats, freeing space on the underlying block device. Recommended for periodic execution on thin disks.
  14. Network Interfaces. The guest-network-get-interfaces command. Returns detailed information about guest network adapters. The response contains interface names, MAC addresses, assigned IP addresses with mask prefixes, and transmitted packet statistics. The data is used by orchestration systems for network inventory and connectivity debugging without directly logging into the virtual machine.
  15. OS Information. The guest-get-osinfo command. Extracts identification data of the installed guest operating system. Returned fields include the kernel name, OS version, distribution identifier, and architecture. The function allows the hypervisor to automatically select optimal virtual hardware parameters, such as chipset type or CPU model.
  16. Memory Configuration. The guest-get-memory-blocks and guest-set-memory-blocks commands. Provide online management of memory blocks in Linux guests. The get command returns a list of segments available for hot-add or removal. The set command allows activating or deactivating specific blocks. This is a key element for dynamically changing the amount of RAM without rebooting the virtual machine.
  17. Hardware Inventory. The guest-get-disks and guest-get-fsinfo commands. guest-get-disks lists the guest block devices. guest-get-fsinfo provides a map of mount points indicating the filesystem type and used space. The agent allows mapping virtual disks visible to the hypervisor to logical volumes inside the OS, which is important for backup.
  18. User Management. The guest-set-user-password command. Changes the password of a specified user account in the guest system. The command accepts the new password as a base64 string, optionally already hashed by the crypt function for encrypted transmission. Used for emergency access recovery to a virtual machine or for initial initialization of instances created from a template.
  19. RPC Filtering and Security. A mechanism to restrict the set of available commands using the --allow-rpcs and --block-rpcs parameters in the qemu-ga configuration file. The administrator can explicitly allow or deny specific interfaces. In production environments, it is strictly recommended to disable guest execution (guest-exec) and file access commands to minimize the attack surface.
  20. Socket Interaction. The agent on the host side is represented by a Unix socket with a name corresponding to the virtual machine ID. This allows management-level utilities, such as virsh or pvesh, as well as custom scripts via socat, to directly send JSON requests. This approach provides a low-level interface for integration without using higher-order APIs.

Comparisons

  • QEMU Guest Agent vs Open-VM-Tools. QEMU Guest Agent is a lightweight daemon operating through a paravirtualized VirtIO-Serial channel, while Open-VM-Tools is oriented towards the proprietary VMware stack and contains modules for working with HGFS and VMCI. If QGA is minimalistic and universal for KVM environments, OVT integrates a graphics driver and Memory Ballooning, creating a heavier but deeply integrated infrastructure within the vSphere ecosystem.
  • KVM (Turns the Linux kernel into a hypervisor)
  • QEMU Guest Agent vs Hyper-V Data Exchange Service (KVP). Both mechanisms solve the task of metadata exchange between host and guest, however, they implement fundamentally different transport protocols. QGA uses a dedicated serial port with JSON-formatted commands, ensuring cross-platform capability, whereas Hyper-V KVP relies on the VMBus and manipulates Windows registry keys, making it native to Windows but creating a rigid binding to the Microsoft hypervisor.
  • VMBus (Hypervisor-to-Guest communication channel)
  • QEMU Guest Agent vs cloud-init. Unlike QGA, which operates as a runtime background service for filesystem freezing (fsfreeze) and executing commands from the host, cloud-init functions during the initial boot stage. Cloud-init specializes in one-time initialization: setting SSH keys and hostname before login, while QGA does not configure the OS but provides a continuous orchestration channel for live migrations and backups without downtime.
  • QEMU Guest Agent vs Libvirt Hooks. QGA provides an interface for executing commands directly inside the guest context (guest-exec), whereas Libvirt Hooks trigger exclusively on the host system side on virtual machine lifecycle events. The fundamental difference is in the isolation level: Hooks do not require network or agent connectivity with the guest OS but are limited to QEMU process triggers, whereas QGA is capable of atomically executing applications inside the isolated environment.
  • QEMU Guest Agent vs SPICE Agent (vdagent). Although both agents use the VirtIO-Serial channel, their functional domains are different. SPICE Agent is responsible for the client experience: screen resolution settings, shared clipboard, and cursor migration in the remote access console. QEMU Guest Agent, on the contrary, lacks a graphical context and focuses on system administration, managing network configuration, memory snapshots, and guest OS state reporting for external orchestrators.

OS and driver support

QEMU Guest Agent (qemu-ga) runs inside the virtual machine and communicates with the host via a virtio-serial channel, for which a virtio-serial driver must be installed in the guest OS. On Windows, this is achieved by installing the driver from the virtio-win package, where the device may initially be identified as a PCI Simple Communications Controller. The agent officially supports a wide range of Windows (from XP/2003 to 8.1/2012 R2) and many Linux distributions, and installation on Linux comes down to installing the qemu-guest-agent package and verifying that the system service is running.

Security

To prevent unauthorized access from the hypervisor, a fine-tuning mechanism for available commands is implemented: using --block-rpcs (blacklist) or --allow-rpcs (whitelist) options, potentially dangerous calls can be blocked, for example, guest file I/O (guest-file-open, guest-file-read, guest-file-write, and others). This allows the administrator to limit the host’s ability to modify the filesystem or obtain data while preserving critically important functions like guest-shutdown. Settings are applied through the qemu-ga.conf configuration file or environment variables in a systemd unit.

Logging

By default, qemu-ga outputs logs to stderr, but when running as a daemon it writes to a specified file via the --logfile option. The detail level is regulated by the --verbose flag, and standard glib levels are also supported (error, critical, warning, info, debug). When the guest filesystem hangs, logging may be disabled by the agent itself to avoid I/O locks. In the Windows version, the QEMU-GA service status and possible errors are routinely monitored through the system Event Viewer.

Limitations

A key limitation is the operation of file operations (guest-file-open/read/write), which become unavailable or dangerous when the filesystem is frozen by the guest-fsfreeze-freeze command: to prevent mutual locks, the agent persistently tracks the freeze state through a special marker file in /var/run. On Windows, the guest-fsfreeze-freeze operation is implemented via VSS (Volume Shadow Copy Service) and does not work on legacy versions (XP, Server 2003); additionally, filesystem freezing in this implementation is limited by VSS in time (up to approximately 10 seconds).

History and development

The original qemu-ga daemon, written in C using GLib, was proposed in 2011 by IBM and from its first versions supported virtio-serial transport, syslog output, and basic log formatting. Over time, the command protocol was supplemented with mechanisms for freezing individual mount points (guest-fsfreeze-freeze-list), and starting with version 0.15.0, full support for filesystem state management, including guest hook scripts (fsfreeze-hook) launched on freeze/thaw events. Later, vsock transport support was added, simplifying configuration in cloud environments and removing the exclusive dependency on virtio-serial.

Latest publications