是什么
qemu-guest-agent 是运行在 KVM/QEMU 虚机内部的辅助守护进程，宿主侧的 libvirt 通过 virtio-serial 通道（设备名通常为 org.qemu.guest_agent.0）向它下发指令、读取信息。没有 agent 时，宿主要关机只能发 ACPI 信号，也拿不到 guest 内部的网卡地址与文件系统状态；装上 agent 后，查地址、冻结文件系统、代理关机、执行受限命令都能从宿主侧统一发起。VMware 平台上承担同类角色的是 open-vm-tools。
基本信息
| 运行位置 | guest 内部常驻，以 root 权限运行 |
|---|---|
| 通信通道 | virtio-serial 通道，设备名 org.qemu.guest_agent.0 |
| 宿主调用 | virsh qemu-agent-command 域 加一段 JSON 指令 |
| 软件包 | Debian/Ubuntu 与 RHEL 系均为 qemu-guest-agent |
| 服务管理 | systemd 单元 qemu-guest-agent，装完需启动并设为开机自启 |
典型使用场景
- 虚机不走 DHCP 或需要精确地址时，用 virsh domifaddr --source agent 从 guest 内部取回真实 IP
- 做静默快照前冻结文件系统，让磁盘状态与内存状态对齐，备份可直接挂载使用
- 从宿主发关机、重启、改口令等指令，走 agent 通路比 ACPI 信号更可控
- 使用镜像批量交付时重置 guest 内账号口令，避免模板中的旧凭据流出
- 采集 guest 内操作系统类型与版本，用于资产盘点与合规核查
- OpenStack、Proxmox 等平台初始化实例后依赖 agent 回传执行结果
常用调用
常用调用
virsh domifaddr vm1 --source agent # 从 guest 内部取网卡地址
virsh qemu-agent-command vm1 '{"execute":"guest-info"}' # 查询 agent 能力
virsh domfsfreeze vm1 # 冻结文件系统，准备做静默快照
# 此处执行卷快照或备份
virsh domfsthaw vm1 # 解冻，恢复 guest 写盘
virsh domifaddr vm1 --source lease # agent 不可用时改读 DHCP 租约输出逐列读法
| 列 | 含义 | 判读要点 |
|---|---|---|
| Name | 虚拟网卡接口名，如 vnet0 | 应与 virsh domiflist 的输出一致 |
| MAC address | guest 内网卡 MAC | 同一虚机多条记录属正常 |
| Protocol | ipv4 或 ipv6 | 只出现 ipv6 说明没取到 IPv4 地址 |
| Address | 接口地址与掩码长度 | 为空或整表无输出，说明 agent 未生效 |
agent 未安装或服务未启动时，--source agent 会报 guest agent is not responding；此时退回 --source lease 读 DHCP 租约，前提是 guest 确实通过 DHCP 获得地址，静态配置的虚机拿不到结果。
domfsfreeze 冻结期间 guest 内所有写操作被阻塞，必须与 domfsthaw 成对使用；中途快照失败要人工解冻，否则 guest 会长时间挂死。