qemu guest agent 用法
2022-04-29 本文已影响0人
河码匠
虚拟机内需要安装
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。 |
