virsh domifaddr
returns nothing, or you want a clean shutdown but the VM ignores ACPI. The QEMU guest agent solves all of these. It is a small daemon that runs inside the guest and talks to the hypervisor over a virtio-serial channel. Without it, you get crash-consistent snapshots at best and no visibility into what the guest is doing.
The agent bridges the gap between host and guest. The hypervisor sends commands (freeze the filesystem, report your IP, shut down cleanly) and the guest executes them and returns results. No network required, no SSH keys to manage, no polling DHCP leases. This walkthrough shows you how to install qemu-guest-agent in Linux VMs, attach the virtio-serial channel in libvirt, and use the agent for the operations that matter in production.
What the QEMU Guest Agent Does
The QEMU guest agent is a daemon that runs inside your VM and listens on /dev/virtio-ports/org.qemu.guest_agent.0. The host sends JSON-RPC commands over this channel, the agent executes them in the guest context, and returns the results. The transport is virtio-serial, a paravirtualized serial device that bypasses the network entirely. You do not need IP connectivity, firewall rules, or SSH access for the agent to work.
The main capabilities you will use in production: guest-fsfreeze-freeze and guest-fsfreeze-thaw pause and resume filesystem writes so snapshots capture a consistent state, even on a busy database. guest-shutdown triggers a clean shutdown from inside the guest, far more reliable than ACPI. guest-network-get-interfaces reports all IP addresses and MAC addresses, solving the common problem where virsh domifaddr returns empty because the DHCP server is outside libvirt's view. guest-file-open, guest-file-read, guest-file-write let you read and write files in the guest filesystem from the host. guest-set-user-password resets passwords without logging in. guest-exec runs arbitrary commands and returns stdout and stderr.
Without the agent, snapshots are crash-consistent only: what you would get if you pulled the power cord. The filesystem journal will replay on boot, but uncommitted database transactions are lost. IP discovery requires scraping ARP tables, parsing DHCP logs, or scanning the network. Shutdown is an ACPI event that the guest may ignore, forcing you to destroy the VM. The agent solves all of these by giving the hypervisor a direct channel into the guest OS. For a deeper look at the KVM virtualization stack and where the guest agent fits, see KVM Linux Virtualization Complete Guide.
Installing qemu-guest-agent in the Guest
Debian and Ubuntu Installation
On Debian, Ubuntu, and derivatives, install the package and enable the service:
apt update
apt install qemu-guest-agent
systemctl enable --now qemu-guest-agent
The --now flag starts the service immediately. Most cloud images ship with qemu-guest-agent already installed and enabled, but home lab VMs built from standard ISOs will not have it.
RHEL, Rocky, and Alma Installation
On RHEL family distributions, the package name is the same:
dnf install qemu-guest-agent
systemctl enable --now qemu-guest-agent
RHEL 8 and 9, Rocky Linux, AlmaLinux, and Fedora all use this package. CentOS 7 uses yum instead of dnf but the package name is identical.
Verifying the Agent Service
Check that the service is running:
systemctl status qemu-guest-agent
You should see active (running) in the output. The agent logs to /var/log/qemu-ga/qemu-ga.log on most distributions. Now check for the virtio-serial device:
ls -l /dev/virtio-ports/
You should see a symlink org.qemu.guest_agent.0 -> ../vport1p1 or similar. If /dev/virtio-ports/ does not exist or the symlink is missing, the virtio-serial channel is not attached to the VM. The next section fixes that.
Adding the virtio-serial Channel to the VM
Adding the Channel with virt-manager
Open the VM in virt-manager, click "Show virtual hardware details" (the lightbulb icon), then "Add Hardware". Select "Channel" from the list. Set "Device Type" to virtio and "Name" to org.qemu.guest_agent.0 exactly. Click "Finish". Shut down the VM and start it again for the channel to attach. Hotplug works on some kernels but a reboot is safer.
Adding the Channel with virsh edit
For scripted or headless setups, edit the domain XML:
virsh edit vm-name
Inside the <devices> section, add:
<channel type='unix'>
<source mode='bind'/>
<target type='virtio' name='org.qemu.guest_agent.0'/>
</channel>
The type='unix' attribute tells libvirt to create a Unix socket on the host for communication. The target type='virtio' and name='org.qemu.guest_agent.0' are required; the agent will not recognize any other name. A common mistake is setting type='pty', which creates a pseudo-terminal instead of a socket and breaks communication. Another mistake is misspelling the target name: it must match exactly. Save and exit, then reboot the VM. The official libvirt channel documentation covers other channel types, but unix is what you want for the guest agent.
Confirming the Channel Inside the Guest
After the VM boots, log in and check:
ls -l /dev/virtio-ports/
You should now see org.qemu.guest_agent.0 -> ../vport1p1. If it is still missing, check the host side:
virsh dumpxml vm-name | grep -A3 channel
Confirm the channel block is present and the target name is correct. Inside the guest, dmesg | grep virtio will show virtio-serial device detection. If you see virtio-ports vport1p1: error -16 allocating port or similar, the channel type is wrong or the device name conflicts with another channel.
Testing Agent Communication from the Host
Checking Agent Status with virsh
From the host, test the agent with a simple ping:
virsh qemu-agent-command vm-name '{"execute":"guest-ping"}'
A working agent returns:
{"return":{}}
If you see error: Guest agent is not responding, the agent service is not running inside the guest or the virtio-serial channel is misconfigured. Go back and check systemctl status qemu-guest-agent in the guest and virsh dumpxml vm-name | grep -A3 channel on the host. The channel target name must be exactly org.qemu.guest_agent.0.
Querying Guest Information
Once the ping succeeds, query the agent version and supported commands:
virsh qemu-agent-command vm-name '{"execute":"guest-info"}'
The output is a JSON object showing the agent version and a list of supported commands. Sample output:
{"return":{"version":"7.2.0","supported_commands":[{"enabled":true,"name":"guest-shutdown","success-response":true},{"enabled":true,"name":"guest-fsfreeze-freeze","success-response":true},...]}}
The commands are QAPI types defined in the QEMU codebase. For a full list, run qemu-ga --help inside the guest or check the QEMU guest agent reference. Now test IP address retrieval:
virsh domifaddr vm-name --source agent
This returns the guest's IP addresses, MAC addresses, and interface names. Compare to --source lease, which only works if libvirt manages DHCP, or --source arp, which depends on recent traffic. The agent source works regardless of network configuration.
Using the Agent for Filesystem-Consistent Snapshots
Manual Freeze and Snapshot Workflow
To take a snapshot with guaranteed filesystem consistency, freeze the guest filesystems first:
virsh qemu-agent-command vm-name '{"execute":"guest-fsfreeze-freeze"}'
The command flushes all dirty buffers to disk and pauses all writes. The return value shows how many filesystems were frozen:
{"return":3}
Now create the snapshot:
virsh snapshot-create-as vm-name snapshot-2024-01-15 --disk-only --atomic
The --disk-only flag creates an external snapshot of the disk without pausing the VM. Finally, thaw the filesystems:
virsh qemu-agent-command vm-name '{"execute":"guest-fsfreeze-thaw"}'
The freeze times out after 10 seconds by default if you do not thaw manually, so the guest will not stay locked indefinitely. The timeout is a safety mechanism, but it means you must complete the snapshot quickly or the freeze will release before the snapshot finishes.
Automatic Freeze with virsh snapshot-create --quiesce
For a simpler workflow, use the --quiesce flag to freeze, snapshot, and thaw in one command:
virsh snapshot-create-as vm-name snapshot-2024-01-15 --disk-only --quiesce
This only works with --disk-only or when the agent is present. Libvirt calls guest-fsfreeze-freeze, creates the snapshot, then calls guest-fsfreeze-thaw automatically. The difference in filesystem state is significant: a frozen snapshot mounts clean with no journal replay, while an unfrozen snapshot may replay the journal or, on a busy database, show corruption from in-flight writes that were not flushed.
Warning: The freeze pauses all writes, so do not hold it long on a busy database. The automatic thaw on timeout means an incomplete snapshot if the operation takes longer than 10 seconds. For large snapshots, freeze, snapshot the backing store at the storage layer, then thaw immediately.
Common Agent Commands for Production
Graceful Shutdown and Reboot
Trigger a clean shutdown from the host:
virsh qemu-agent-command vm-name '{"execute":"guest-shutdown"}'
For a reboot instead of a shutdown:
virsh qemu-agent-command vm-name '{"execute":"guest-shutdown","arguments":{"mode":"reboot"}}'
This runs shutdown -h now or reboot inside the guest, far more reliable than virsh shutdown vm-name, which sends an ACPI event that the guest can ignore. virsh destroy vm-name is a hard poweroff equivalent to pulling the plug. Use guest-shutdown for maintenance windows and container host reboots where you need every VM to shut down cleanly.
Retrieving Guest Network Configuration
Get all network interfaces, IPs, and MACs:
virsh qemu-agent-command vm-name '{"execute":"guest-network-get-interfaces"}'
Sample output:
{"return":[{"name":"lo","ip-addresses":[{"ip-address":"127.0.0.1","prefix":8,"ip-address-type":"ipv4"}]},{"name":"eth0","hardware-address":"52:54:00:12:34:56","ip-addresses":[{"ip-address":"192.168.122.45","prefix":24,"ip-address-type":"ipv4"}]}]}
This is the only reliable way to get the guest IP when libvirt does not manage DHCP or the VM uses a static IP outside the host's subnet. Parse the JSON to extract the address for inventory scripts or monitoring.
Setting Guest User Passwords
Reset a user password without logging in:
echo -n 'newpassword' | base64
bmV3cGFzc3dvcmQ=
virsh qemu-agent-command vm-name '{"execute":"guest-set-user-password","arguments":{"username":"root","password":"bmV3cGFzc3dvcmQ=","crypted":false}}'
The password must be base64-encoded. Set "crypted":true if you pass a pre-hashed password from /etc/shadow. This is useful for password recovery or automated provisioning when you do not want to inject SSH keys.
File operations use guest-file-open, guest-file-read, guest-file-write, and guest-file-close. To read /etc/hostname, open the file to get a handle, read it, then close:
virsh qemu-agent-command vm-name '{"execute":"guest-file-open","arguments":{"path":"/etc/hostname","mode":"r"}}'
{"return":1000}
virsh qemu-agent-command vm-name '{"execute":"guest-file-read","arguments":{"handle":1000,"count":512}}'
{"return":{"buf-b64":"bXlob3N0bmFtZQo=","count":11,"eof":true}}
virsh qemu-agent-command vm-name '{"execute":"guest-file-close","arguments":{"handle":1000}}'
Decode the base64 buf-b64 to get the content. For running commands, guest-exec returns a PID, then you poll guest-exec-status for stdout and stderr. It is less ergonomic than SSH, but works when the network is unavailable or not yet configured.
Troubleshooting Agent Issues
Agent Not Responding After Installation
If virsh qemu-agent-command vm-name '{"execute":"guest-ping"}' returns error: Guest agent is not responding, start inside the guest. Check the service status:
systemctl status qemu-guest-agent
If inactive, restart it with systemctl restart qemu-guest-agent. If the service fails to start, check the log at /var/log/qemu-ga/qemu-ga.log for errors. Most failures are "Failed to open channel device" or "No such file or directory" for /dev/virtio-ports/org.qemu.guest_agent.0. Confirm the device exists:
ls -l /dev/virtio-ports/
If the symlink is missing, the virtio-serial channel is not attached. Shut down the VM (do not just reboot) and verify the channel in the domain XML:
virsh dumpxml vm-name | grep -A3 channel
If the channel block is absent or the target name is wrong, edit the XML with virsh edit vm-name, add the correct channel, then start the VM. The agent will not work until the channel is present and the VM has been fully powered off and on again.
Channel Errors in dmesg
Inside the guest, run:
dmesg | grep virtio_console
Common errors: virtio-ports vport1p1: Error -2 getting port name means the target name in the XML does not match org.qemu.guest_agent.0. Fix the XML and reboot. virtio-ports vport1p1: error -16 allocating port indicates a conflict with another channel device. Check for duplicate channel entries in virsh dumpxml. If you see virtio-serial: probe of virtio1 failed with error -16, the virtio-serial device itself failed to initialize, often because the channel type is set to pty instead of unix. Change <channel type='pty'> to <channel type='unix'> in the XML.
Timeouts During Freeze Operations
If guest-fsfreeze-freeze times out or returns an error, check the freeze status:
virsh qemu-agent-command vm-name '{"execute":"guest-fsfreeze-status"}'
If it returns {"return":"frozen"}, a previous freeze was not thawed and the filesystems are still paused. Manually thaw:
virsh qemu-agent-command vm-name '{"execute":"guest-fsfreeze-thaw"}'
Or restart the agent inside the guest with systemctl restart qemu-guest-agent, which releases all freezes. If freeze consistently fails with error, the guest kernel may lack fsfreeze support or the filesystem type is unsupported. tmpfs, devtmpfs, and network filesystems do not support freeze. Check mounted filesystems with findmnt -t ext4,xfs,btrfs to confirm supported types are present.
On RHEL and derivatives, SELinux may block file operations or SSH key injection. If guest-file-read returns a permission error, check:
getsebool virt_qemu_ga_read_nonsecurity_files
getsebool virt_qemu_ga_manage_ssh
Enable them if needed with setsebool -P virt_qemu_ga_read_nonsecurity_files on and setsebool -P virt_qemu_ga_manage_ssh on. These booleans allow the agent to read arbitrary files and modify ~/.ssh/authorized_keys.
Security and Access Control Considerations
The QEMU guest agent runs as root inside the guest and can execute arbitrary commands, freeze filesystems, read and write files, and reset passwords. Any user on the hypervisor who can run virsh qemu-agent-command has full control over the guest. Restrict access to the hypervisor shell or use libvirt's polkit rules to limit who can interact with the agent. Do not expose the virtio-serial channel to untrusted users or processes.
The agent is safer than SSH for automation in one sense: it requires no network exposure, no SSH keys to rotate, no password authentication, and no open ports. An attacker who compromises the guest cannot pivot to the hypervisor over the agent channel. The reverse is not true. A compromised hypervisor has total control over every guest with an agent installed. You must trust the hypervisor completely. If you run untrusted workloads, do not install the agent or remove the channel from the VM configuration.
Cloud-init, Ignition, and similar provisioning tools often use the agent channel to inject SSH keys, set hostnames, and configure network settings on first boot. If you use these tools, the agent must be installed and the channel must be attached. If you do not need the agent for snapshots, IP discovery, or provisioning, the safest option is to not install qemu-guest-agent at all. If the package is installed but the service is disabled, the attack surface is minimal: the agent cannot respond to commands until the service starts. If you need the agent for snapshots but want to disable file and exec operations, no per-command access control exists; the agent either works or does not. Uninstall the package or remove the channel when the agent is not required.
Checklist: Deploying the Guest Agent Across Your Fleet
For a consistent rollout of the guest agent across all your VMs, work through these steps:
- Install the package in every guest:
apt install qemu-guest-agenton Debian/Ubuntu,dnf install qemu-guest-agenton RHEL family. Enable the service withsystemctl enable --now qemu-guest-agent. - Add the virtio-serial channel to every VM: Use
virsh edit vm-nameto add the channel block if it is missing. Shut down and start each VM for the channel to attach. Automate this with a script that checksvirsh dumpxmlfor the channel, adds it if absent, then powers off and on. - Test agent communication on every VM: Run
virsh qemu-agent-command vm-name '{"execute":"guest-ping"}'and confirm{"return":{}}. Checkvirsh domifaddr vm-name --source agentreturns IPs. - Update snapshot scripts to use --quiesce: Replace
virsh snapshot-create-aswithvirsh snapshot-create-as --disk-only --quiesceto get filesystem-consistent snapshots automatically. - Lock down hypervisor access: Restrict who can run
virsh qemu-agent-command. Use polkit rules or limit shell access. Document that the agent runs as root and can execute arbitrary commands. - Monitor freeze timeouts: If snapshots fail because the freeze times out, switch to freezing at the storage layer or reduce the snapshot window. The 10-second timeout is not configurable.
For deeper coverage of KVM, libvirt, and production VM management, see the Dargslan eBook Linux Virtualization Stack: QEMU, KVM, libvirt, and virt-manager, which covers guest agent integration in the context of automated snapshot workflows and VM provisioning pipelines.
Frequently Asked Questions
What is the QEMU guest agent used for?
The QEMU guest agent enables the hypervisor to send commands directly to the guest OS over a virtio-serial channel. It is used for filesystem-consistent snapshots (freeze and thaw), graceful shutdowns, IP address discovery, password resets, file operations, and running commands inside the guest without SSH or network access. The agent runs as root in the guest and executes commands sent by the host.
How do I install qemu-guest-agent on Ubuntu or RHEL?
On Ubuntu and Debian, run apt install qemu-guest-agent then systemctl enable --now qemu-guest-agent. On RHEL, Rocky, Alma, and Fedora, run dnf install qemu-guest-agent then systemctl enable --now qemu-guest-agent. After installation, confirm the service is active with systemctl status qemu-guest-agent and check that /dev/virtio-ports/org.qemu.guest_agent.0 exists inside the guest.
Why does virsh domifaddr return nothing without the guest agent?
virsh domifaddr with --source lease only works if libvirt manages the DHCP server for the VM's network. If the VM gets its IP from an external DHCP server or uses a static IP, libvirt has no lease data. The --source arp option depends on recent traffic and ARP cache entries. The --source agent option queries the guest agent for all interfaces, IPs, and MACs directly from the guest OS, which works regardless of network configuration.
How do I add a virtio-serial channel to an existing VM?
Shut down the VM completely, then run virsh edit vm-name. Inside the <devices> section, add <channel type='unix'><source mode='bind'/><target type='virtio' name='org.qemu.guest_agent.0'/></channel>. Save and exit, then start the VM. Confirm the channel with virsh dumpxml vm-name | grep -A3 channel and check for /dev/virtio-ports/org.qemu.guest_agent.0 inside the guest. A full poweroff and poweron is required; a reboot may not attach the channel.
What happens if I forget to thaw a filesystem after guest-fsfreeze-freeze?
The freeze times out automatically after 10 seconds by default, so the guest will not stay locked indefinitely. If you check guest-fsfreeze-status and it still shows frozen, manually thaw with virsh qemu-agent-command vm-name '{"execute":"guest-fsfreeze-thaw"}' or restart the agent service inside the guest with systemctl restart qemu-guest-agent, which releases all freezes. A frozen filesystem blocks all writes until thawed or timed out.