qemu guest agent 用法

虚拟机内需要安装 qemu-guest-agent
并启动 systemctl start qemu-guest-agent

一，命令

virsh qemu-agent-command 虚拟机 --cmd 参数

参数说明：

说明中示例省略 virsh qemu-agent-command 虚拟机 --cmd 这部分

命令	说明	示例
guest-info	获取 agent 支持的命令	'{"execute":"guest-info"}'
guest-sync-delimited	宿主机发送一个 int 数字给 qga，qga 返回这个数字，并且在后续返回字符串响应中加入 ascii 码为 0xff 的字符。	'{"execute":"guest-sync-delimited"}'
guest-sync	示例1	示例1
guest-ping	ping 虚机 agent，无错误返回表示成功	'{"execute":"guest-ping"}'
guest-get-time	获取虚拟机系统时间	'{"execute":"guest-get-time"}'
guest-set-time	设置虚机时间	示例2
guest-info	获取当前 qga 支持的命令列表以及版本信息等	'{"execute":"guest-info"}'
guest-shutdown	开启虚拟机关机任务，其为异步命令，不保证关机成功	示例3
guest-file-open	打开虚拟机内文件并返回文件 handle	示例3
guest-file-read	读取打开文件的内容	示例4
guest-file-write	写文件	示例5
guest-file-close	关闭打开的文件	'{"execute":"guest-file-close", "arguments":{"handle": 1000}}'
guest-file-seek	与 fseek() 一样，查找文件中的某个位置，然后返回当前文件位置。还封装了 ftell() 的功能，offset=0，whence=1	示例6
guest-file-flush	将用户缓冲区数据写入磁盘或内核缓冲区	'{"execute":"guest-file-seek", "arguments":{"handle": 1000}}'
guest-fsfreeze-status	获取虚拟机文件冻结状态 thawed： 解冻 frozen：冻结	'{"execute":"guest-fsfreeze-status"}'
guest-fsfreeze-freeze	同步并冻结虚拟机文件系统 返回： 返回目前冻结的文件个数，如果执行错误，则解冻当前所有文件	'{"execute":"guest-fsfreeze-freeze"}'
guest-fsfreeze-freeze-list	同步和冻结指定的虚拟机文件	示例7
guest-fsfreeze-thaw	冻结所有文件	'{"execute":"guest-fsfreeze-thaw"}'
guest-fstrim	丢弃（或“修剪”）文件系统未使用的空间	示例8
guest-suspend-disk	挂起虚拟机磁盘，如成功则不返回值 尝试三种策略： systemd hibernate pm-utils (via pm-hibernate) manual write into sysfs	'{"execute":"guest-suspend-disk"}'
guest-suspend-ram	挂起虚拟机 ram。策略同上	'{"execute":"guest-suspend-ram"}'
guest-network-get-interfaces	获取虚拟机IP地址，MAC地址，子网掩码	'{"execute":"guest-network-get-interfaces"}'
guest-get-vcpus	检索客户的逻辑处理器列表。这是一个只读操作 返回虚机所有 VCPU 的列表。无序	'{"execute":"guest-get-vcpus"}'
guest-set-vcpus	尝试重新配置客户内部的逻辑处理器(当前:启用/禁用)。	示例9
guest-get-fsinfo	获取在虚拟机中挂载的文件系统列表	'{"execute":"guest-get-fsinfo"}'
guest-set-user-password	设置用户密码	示例10
guest-get-memory-block	获取虚拟内存信息
guest-exec	执行命令	示例11
guest-exec-status	查看 guest-exec 执行后返回的 pid。获取数据	示例12
guest-get-host-name	返回机器名称	'{"execute":"guest-get-host-name"}'
guest-get-timezone	获取虚拟机时区信息	'{"execute":"guest-get-timezone"}'
guest-get-osinfo	获取操作系统信息	'{"execute":"guest-get-osinfo"}'

官方文档

二、命令示例

示例 1. guest-sync

以下为官方文档翻译
回文唯一的整数，这个命令进行测试。

这个命令用于确保 client 与 guest agent 是同步的，不包含之前 client 旧数据。在返回提供的唯一整数值之前， guest agent 忽略所有响应，并且由 client 以可以获取此响应的方式处理陈旧的全部或部分传递的 JSON 文本。

在 client 之前收到部分旧响应的情况下，这不能总是可靠地完成。一种特殊情况是，如果 qemu-ga 响应被逐个字符地馈送到 JSON 解析器中。在这些情况下，使用 guest-sync-delimited 可能是最佳选择。

对于逐行获取响应并将其转换为 JSON 对象的客户端，guest-sync 应该就足够了，但请注意，在通道脏的情况下，一些解析响应的尝试可能会导致解析器错误。

此类客户端还应在此命令之前使用 0xFF 字节，以确保来宾代理刷新来自先前会话的任何部分读取的 JSON 数据。

Arguments：

命令	说明
id	整数

示例：

virsh qemu-agent-command xxx --cmd '{"execute":"guest-sync", "arguments":{"id":123123}}'
# 成功返回
{"return":123123}

示例 2. guest-set-time

当 client 暂停或迁移后，client 操作系统时间会出现差值。根据间隔的时间长短，NTP 可能无法重新同步。此命令尝试将 client 的系统时间设置为给定值，然后将硬件时钟 (RTC) 设置为当前系统时间。

如果未指定时间，则从 RTC 读取要设置的时间。但是，并非所有平台（即 Windows）都支持此功能。

Arguments：

命令	说明
time	整数，这是一个纳秒的时间

示例：

virsh qemu-agent-command xxx --cmd '{"execute":"guest-set-time", "arguments":{"time": 1580637675389882900}}'
# 成功返回
{"return":{}}

示例 2. guest-shutdown

Arguments：

命令	说明
mode	参数： halt：停止 powerdown：默认 断电 reboot：重启

示例：

virsh qemu-agent-command xxx --cmd '{"execute":"guest-set-time", "arguments":{"time": 1580637675389882900}}'
# 成功返回
{"return":{}}

示例 3. guest-file-open

Arguments：

命令	说明
path	文件在虚机内的完整路径
mode	打开模式，根据 fopen()，r 是默认值。

示例：

virsh qemu-agent-command xxx --cmd '{"execute":"guest-file-ope", "arguments":{"path": "/root/123.txt"}}'
# 成功返回
{"return":1000}

示例 4. guest-file-read

Arguments：

命令	说明
handle	guest-file-open 时返回的文件 handle
count	要读取的最大字节数（默认为 4KB，最大为 48MB）

示例：

virsh qemu-agent-command xxx --cmd '{"execute":"guest-file-read", "arguments":{"handle": 1000}}'
# 成功返回
{"return":{"count":535,"buf-b64":"IyEgL2Jpbi9i......yBkb25lCg==","eof":true}}

示例 5. guest-file-write

Arguments：

命令	说明
handle	guest-file-open 时返回的文件 handle
buf-b64	文件内容，转化为 base64
count	要写入的字节数（实际字节数，base64-decode 之后），默认是 base64 解码后 buf-b64 缓冲区中的所有内容

示例：

virsh qemu-agent-command xxx --cmd '{"execute":"guest-file-write", "arguments":{"handle": 1000, "buf-b64": "IyEgL2Jpbi9i......yBkb25lCg=="}}'

示例 6. guest-file-seek

Arguments：

命令	说明
handle	int 类型 guest-file-open 时返回的文件 handle
offset	int 类型 文件流中要跳过的字节
whence	int 类型 用于解释偏移的符号或数字代码

示例：

virsh qemu-agent-command i-prsqxjon --cmd '{"execute":"guest-file-seek", "arguments":{"handle": 1001, "offset": 10, "whence": 0}}'

# 成功返回
{"return":{"eof":false,"position":10}}

示例 7. guest-fsfreeze-freeze-list

Arguments：

命令	说明
mountpoints	冻结文件数组

示例：

virsh qemu-agent-command i-prsqxjon --cmd '{"execute":"guest-file-seek", "arguments":{"handle": 1001, "offset": 10, "whence": 0}}'

# 成功返回
当前冻结的文件系统数。出错时，所有文件系统都将被解冻。

示例 8. guest-fstrim

Arguments：

命令	说明
minimum	int类型 要丢弃的最小连续可用范围，以字节为单位。小于此的自由范围可能会被忽略（这是一个提示，客人可能不会尊重它）。通过增加此值，fstrim 操作将更快地完成具有严重碎片可用空间的文件系统，尽管并非所有块都将被丢弃。默认值为零，表示“丢弃每个空闲块”。

示例：

virsh qemu-agent-command i-prsqxjon --cmd '{"execute":"guest-fstrim", "arguments":{"minimum": 10}}'

# 成功返回一个 GuestFilesystemTrimResponse，其中包含所有修剪路径的状态。

示例 9. guest-set-vcpus

Arguments：

命令	说明
vcpus	数组类型 参数： logical-id: int VCPU 的 guest-specific 特定的唯一标识符。 online: boolean VCPU 是否启用。 can-offline: boolean 是否可以使 VCPU 脱机

示例 10. guest-set-user-password

Arguments：

命令	说明
vcpus	数组类型 参数： logical-id: int VCPU 的 guest-specific 特定的唯一标识符。 online: boolean VCPU 是否启用。 can-offline: boolean 是否可以使 VCPU 脱机

示例 11. guest-exec

Arguments：

命令	说明
path	执行的路径或名称
arg	array 执行命令所需参数
env	array 执行所需的环境变量
input-data	要传递给进程标准输入的数据（base64 编码）
capture-output	bool 标志以启用正在运行的进程的标准输出/标准错误的捕获。默认为 False。

示例：

virsh qemu-agent-command i-prsqxjon --cmd '{"execute":"guest-exec", "arguments":{"path":"ls","capture-output":true}}'
# 返回 pid
{"return":{"pid":19099}}

示例 11. guest-exec-status

Arguments：

命令	说明
pid	guest-exec 返回的 pid

示例：

virsh qemu-agent-command i-prsqxjon --cmd '{"execute":"guest-exec-status", "arguments":{"pid":19099}}'

# 成功返回
{"return":{"exitcode":0,"out-data":"YmluZG......ZAo=","exited":true}}

返回参数

命令	说明
exited	如果进程已经终止，则为 true。
exitcode	如果正常终止，则处理退出代码。
signal	如果进程异常终止，信号编号 (linux) 或未处理的异常代码 (windows)。
out-data	进程的 base64 编码标准输出
err-data	进程的 base64 编码标准错误 ：仅当为guest-exec 指定了 capture-output 时，才会出现 out-data 和 err-data
out-truncated	如果由于大小限制而未完全捕获标准输出，则为 true。
err-truncated	如果由于大小限制而未完全捕获 stderr，则为 true。