qemu-img命令手册

摘自 https://www.hqyman.cn/post/16246.html

qemu-img - QEMU磁盘镜像实用程序

用法：qemu-img 命令【命令选项】

qemu-img command [command options]

描述：qemu-img 允许您离线创建、转换和修改镜像。它可以处理QEMU支持的所有镜像格式。

警告：切勿使用qemu-img修改正在运行的虚拟机或任何其他进程正在使用的镜像；这可能会破坏镜像。另外，请注意，查询正在被另一个进程修改的镜像可能会遇到不一致的状态。

选项

支持以下命令：

check [-q] [-f fmt] [--output=ofmt] [-r [leaks | all]] [-T src_cache] filenamecreate [-q] [-f fmt] [-o options] filename [size]commit [-q] [-f fmt] [-t cache] filenamecompare [-f fmt] [-F fmt] [-T src_cache] [-p] [-q] [-s] filename1 filename2convert [-c] [-p] [-q] [-n] [-f fmt] [-t cache] [-T src_cache] [-O output_fmt] [-o options] [-s snapshot_name] [-S sparse_size] filename [filename2 [...]] output_filenameinfo [-f fmt] [--output=ofmt] [--backing-chain] filenamemap [-f fmt] [--output=ofmt] filenamesnapshot [-q] [-l | -a snapshot | -c snapshot | -d snapshot] filenamerebase [-q] [-f fmt] [-t cache] [-T src_cache] [-p] [-u] -b backing_file [-F backing_fmt] filenameresize [-q] filename [+ | -]sizeamend [-q] [-f fmt] [-t cache] -o options filename

命令参数：

filename：文件名，即磁盘镜像文件名称

fmt：格式，磁盘镜像格式。在大多数情况下，它是自动猜测的。有关支持的磁盘格式的说明，请参见下文。

--backing-chain：将枚举有关磁盘镜像链中的备份文件的信息。请参阅下面的进一步说明。

size：规格，是以字节为单位的磁盘镜像大小。支持可选后缀“k”或“K”（千字节，1024）、“M”（兆字节，1024k）和“G”（千兆字节，1024M）和T（太字节，1024G）。“b”被忽略。

output_filename：输出文件名，即目标磁盘镜像文件名

output_fmt：输出格式，即目标格式

options：选项，是以逗号分隔的格式特定选项列表，格式为name=value格式。使用“-o？”有关使用的格式支持的选项的概述，或参阅下面的格式说明了解详细信息。

-c，表示必须压缩目标镜像（仅限qcow格式）。

-h，有或没有命令显示帮助并列出支持的格式。

-p，显示进度条（仅比较、转换和变基命令）。如果-p选项未用于支持它的命令，则在进程收到“SIGUSR1”信号时报告进度。

-q，安静模式，不打印任何输出（错误除外）。如果同时使用-q和-p选项，则没有进度条。

-S，size，规格。表示qemu-img在转换过程中创建稀疏镜像必须只包含零的连续字节数。此值向下舍入到最接近的512字节。您可以使用常见的大小后缀，例如“k”来表示千字节。

-t，cache，缓存。指定应与（目标）文件一起使用的缓存模式。有关允许的值，请参阅模拟器的“-drive cache=...”选项的文档。

-T，src_cache，源缓存，指定应与源文件一起使用的缓存模式。有关允许的值，请参阅模拟器的“-drive cache=...”选项的文档。

快照snapshot子命令的参数：

snapshot，即要创建、应用或删除的快照的名称。

-a，应用快照（将磁盘恢复到保存状态）。

-c，创建快照。

-d，删除快照。

-l，列出给定镜像中的所有快照。

比较compare子命令的参数：

-f，第一种镜像格式。

-F，第二种镜像格式。

-s， Strict mode，严格模式，无法在不同的镜像大小或扇区上分配。

转换convert子命令的参数：

-n，跳过创建目标卷。

命令说明：

check [-f fmt] [--output=ofmt] [-r [leaks | all]] [-T src_cache] filename

对磁盘镜像文件名执行一致性检查，该命令可以输出格式为“human”或“json”的mt。

如果指定了“-r”，qemu-img 会尝试修复检查过程中发现的任何不一致。“-r leaks”只修复集群泄漏，而“-r all”修复各种错误，选择错误修复或隐藏已经发生的损坏的风险更高。

只有“qcow2”、“qed”和“vdi”格式支持一致性检查。

create [-f fmt] [-o options] filename [size]

创建大小为size和格式为fmt的新磁盘镜像文件名。根据文件格式，您可以添加一个或多个选项来启用此格式的附加功能。

如果指定了选项backing_file，则镜像将仅记录与backing_file的差异。在这种情况下不需要指定大小。除非您使用“commit”监控命令（或qemu-img提交），否则backing_file永远不会被修改。

大小也可以使用带有“-o”的大小选项指定，在这种情况下不需要单独指定。

commit [-f fmt] [-t cache] filename

将记录在文件名中的更改提交到其基础镜像或备份文件中。如果后备文件小于快照，则后备文件的大小将调整为与快照相同的大小。如果快照小于后备文件，则不会截断后备文件。如果您希望备份文件与较小快照的大小相匹配，您可以在提交操作成功完成后自行安全地截断它。

compare [-f fmt] [-F fmt] [-T src_cache] [-p] [-s] [-q] filename1 filename2

检查两个镜像是否具有相同的内容。您可以比较具有不同格式或设置的镜像。

除非您通过 -f（用于文件名 1）和/或 -F（用于文件名 2）选项指定格式，否则会探测格式。

默认情况下，如果较大的镜像在另一个镜像结束后的区域中仅包含未分配和/或归零的扇区，则认为具有不同大小的镜像相同。此外，如果任何扇区未在一个镜像中分配并且在第二个镜像中仅包含零字节，则将其评估为相等。您可以通过指定-s选项来使用严格模式。当在严格模式下运行比较时，如果镜像大小不同或在一个镜像中分配了扇区而在第二个镜像中未分配扇区，则会失败。

默认情况下，比较会打印出结果消息。此消息显示两个镜像相同或第一个不同字节的位置的信息。此外，如果使用严格模式，结果消息可以报告不同的镜像大小。

如果镜像相等，则将exits与0进行比较，如果镜像不同，则将exits与1进行比较。其他退出代码表示执行期间发生错误，标准错误输出应包含错误消息。下表总结了 compare 子命令的所有退出代码：

0：镜像相同1：镜像不同2：打开镜像出错3：检查扇区分配时出错4：读取数据错误

convert [-c] [-p] [-n] [-f fmt] [-t cache] [-T src_cache] [-O output_fmt] [-o options] [-s snapshot_name] [-S sparse_size] filename [filename2 [...]] output_filename

使用格式output_fmt将磁盘镜像文件名或快照snapshot_name转换为磁盘镜像 output_filename。它可以选择压缩（“-c”选项）或使用任何格式特定选项，如加密（“-o”选项）。

只有“qcow”和“qcow2”格式支持压缩。压缩是只读的。这意味着如果一个压缩扇区被重写，那么它将被重写为未压缩的数据。

当使用诸如“qcow”之类的可增长格式时，镜像转换对于获得更小的镜像也很有用：从目标镜像中检测并抑制空扇区。

sparse_size 表示连续的字节数（默认为 4k），必须只包含零，以便 qemu-img 在转换期间创建稀疏镜像。如果 sparse_size 为 0，则不会扫描源以查找未分配或零扇区，而目标镜像将始终被完全分配。

您可以使用 backing_file 选项强制将输出镜像创建为指定基础镜像的写入时副本；backing_file 应该与输入的基本镜像具有相同的内容，但是路径、镜像格式等可能会有所不同。

如果指定了“-n”选项，将跳过目标卷的创建。如果已经使用无法通过 qemu-img 提供的站点特定选项创建了目标卷，这对于诸如“rbd”之类的格式很有用。

info [-f fmt] [--output=ofmt] [--backing-chain] filename

提供有关磁盘镜像文件名的信息。特别是使用它来了解磁盘上保留的大小，该大小可能与显示的大小不同。如果VM快照存储在磁盘镜像中，它们也会显示出来。该命令可以输出格式为“human”或“json”的mt。

如果磁盘镜像具有后备文件链，则可以使用选项“--backing-chain”递归枚举链中每个磁盘镜像的信息。

例如，如果您有一个镜像链，例如：

base.qcow2 <- snap1.qcow2 <- snap2.qcow2

要枚举上述链中每个磁盘镜像的信息，从上到下，请执行以下操作：

qemu-img info --backing-chain snap2.qcow2map [-f fmt] [--output=ofmt] filename

转储镜像文件名及其后备文件链的元数据。特别是，此命令转储文件名的每个扇区的分配状态，以及在后备文件链中分配它的最顶层文件。

两种选项格式是可能的。默认格式（“human”）仅转储文件的已知非零区域。文件的已知零部分被完全省略，对于未在整个链中分配的部分也是如此。qemu-img 输出将标识可以从中读取数据的文件，以及文件中的偏移量。每行将包括四个字段，其中前三个是十六进制数字。例如第一行：

Offset       Length       Mapped to       File0            0x20000      0x50000         /tmp/overlay.qcow20x100000     0x10000      0x95380000      /tmp/backing.qcow2

表示镜像中从偏移量 0 开始的 0x20000 (131072) 字节在 /tmp/overlay.qcow2 （以“原始”格式打开）中可用，从偏移量 0x50000 (327680) 开始。如果使用“人工”格式，压缩、加密或以其他方式无法以原始格式提供的数据将导致错误。请注意，文件名可以包含换行符，因此在脚本中解析这种输出格式是不安全的。

替代格式“json”将返回 JSON 格式的字典数组。它将在“开始”、“长度”、“偏移”字段中包含类似的信息；它还将包括其他更具体的信息：

- 扇区是否包含实际数据（布尔字段“数据”；如果为假，则扇区未分配或存储为优化的全零簇）；

- 数据是否已知读取为零（布尔字段“零”）；

- 为了使输出更短，将目标文件表示为“depth”；例如，深度为 2 是指 filename 的后备文件的后备文件。

在 JSON 格式中，“offset”字段是可选的；在“human”格式会忽略输入或退出并出现错误的情况下，它不存在。如果“data”为假且存在“offset”字段，则文件中的相应扇区尚未使用，但已预先分配。

有关更多信息，请参阅 QEMU 源代码中的 include/block/block.h。

snapshot [-l | -a snapshot | -c snapshot | -d snapshot ] filename

列出、应用、创建或删除镜像文件名中的快照。

rebase [-f fmt] [-t cache] [-T src_cache] [-p] [-u] -b backing_file [-F backing_fmt] filename

更改镜像的支持文件。只有“qcow2”和“qed”格式支持更改备份文件。

后备文件更改为backing_file，并且（如果文件名的镜像格式支持此）后备文件格式更改为backing_fmt。如果 backing_file 被指定为“”（空字符串），那么镜像将重新基于无后备文件（即它将独立于任何后备文件而存在）。

cache 指定用于文件名的缓存模式，而 src_cache 指定用于读取备份文件的缓存模式。

“rebase”可以在两种不同的模式下运行：

安全模式

这是默认模式并执行真正的变基操作。新的备份文件可能与旧的不同，并且 qemu-img rebase 将负责保持文件名的访客可见内容不变。

为了实现这一点，backing_file 和 filename 的旧后备文件之间的任何集群在实际更改后备文件之前都会合并到文件名中。

请注意，安全模式是一项昂贵的操作，与转换镜像相当。它仅在旧的备份文件仍然存在时才有效。

不安全模式

如果指定了“-u”，qemu-img 使用不安全模式。在此模式下，仅更改后备文件名和文件名格式，而不检查文件内容。用户必须注意指定正确的新备份文件，否则镜像的访客可见内容将被破坏。

此模式对于重命名或将支持文件移动到其他位置很有用。它可以在没有可访问的旧支持文件的情况下使用，即您可以使用它来修复其支持文件已被移动/重命名的镜像。

您可以使用“rebase”对两个磁盘镜像执行“diff”操作。当您复制或克隆主机时，这可能很有用，并且您希望在模板或基础镜像之上恢复精简镜像。

假设“base.img”已通过复制被克隆为“modified.img”，并且“modified.img”客户机已运行，因此与“base.img”相比现在有一些变化。要构建一个仅包含差异的名为“diff.qcow2”的精简镜像，请执行以下操作：

qemu-img create -f qcow2 -b modified.img diff.qcow2qemu-img rebase -b base.img diff.qcow2

此时，可以丢弃“modified.img”，因为“base.img + diff.qcow2”包含相同的信息。

resize filename [+ | -]size

更改磁盘镜像，就好像它是按大小创建的一样。

在使用此命令收缩磁盘镜像之前，您必须使用VM内部的文件系统和分区工具来相应地减少分配的文件系统和分区大小。否则将导致数据丢失！

使用此命令增大磁盘镜像后，您必须使用 VM 内的文件系统和分区工具才能真正开始使用设备上的新空间。

amend [-f fmt] [-t cache] -o options filename

修改镜像文件文件名的镜像格式特定选项。并非所有文件格式都支持此操作。

笔记

支持的镜像文件格式：

raw

原始磁盘镜像格式（默认）。这种格式的优点是简单且易于导出到所有其他模拟器。如果您的文件系统支持holes（例如在Linux上的ext2或ext3或Windows上的NTFS中），那么只有写入的扇区会保留空间。使用“qemu-img info”了解镜像使用的实际大小或 Unix/Linux 上的“ls-ls”。

支持的选项：