1QEMU-IMG(1) QEMU-IMG(1)
2
6 qemu-img - QEMU disk image utility
7
9 usage: qemu-img command [command options]
10
12 qemu-img allows you to create, convert and modify images offline. It
13 can handle all image formats supported by QEMU.
14 Warning: Never use qemu-img to modify images in use by a running
16 virtual machine or any other process; this may destroy the image. Also,
17 be aware that querying an image that is being modified by another
18 process may encounter inconsistent state.
19
21 The following commands are supported:
22 check [-f fmt] [--output=ofmt] [-r [leaks | all]] [-T src_cache]
24 filename
25 create [-f fmt] [-o options] filename [size]
26 commit [-f fmt] [-t cache] filename
27 compare [-f fmt] [-F fmt] [-T src_cache] [-p] [-s] filename1 filename2
28 convert [-c] [-p] [-f fmt] [-t cache] [-T src_cache] [-O output_fmt]
29 [-o options] [-S sparse_size] filename [filename2 [...]]
30 output_filename
31 info [-f fmt] [--output=ofmt] filename
32 map [-f fmt] [--output=ofmt] filename
33 snapshot [-l | -a snapshot | -c snapshot | -d snapshot] filename
34 rebase [-f fmt] [-t cache] [-T src_cache] [-p] [-u] -b backing_file [-F
35 backing_fmt] filename
36 resize filename [+ | -]size
37 Command parameters:
39 filename
41 is a disk image filename
42 fmt is the disk image format. It is guessed automatically in most
44 cases. See below for a description of the supported disk formats.
45 size
47 is the disk image size in bytes. Optional suffixes "k" or "K"
48 (kilobyte, 1024) "M" (megabyte, 1024k) and "G" (gigabyte, 1024M)
49 and T (terabyte, 1024G) are supported. "b" is ignored.
50 output_filename
52 is the destination disk image filename
53 output_fmt
55 is the destination format
56 options
58 is a comma separated list of format specific options in a
59 name=value format. Use "-o ?" for an overview of the options
60 supported by the used format or see the format descriptions below
61 for details.
62 -c indicates that target image must be compressed (qcow format only)
64 -h with or without a command shows help and lists the supported
66 formats
67 -p display progress bar (compare, convert and rebase commands only).
69 If the -p option is not used for a command that supports it, the
70 progress is reported when the process receives a "SIGUSR1" signal.
71 -S size
73 indicates the consecutive number of bytes that must contain only
74 zeros for qemu-img to create a sparse image during conversion. This
75 value is rounded down to the nearest 512 bytes. You may use the
76 common size suffixes like "k" for kilobytes.
77 -t cache
79 specifies the cache mode that should be used with the (destination)
80 file. See the documentation of the emulator's "-drive cache=..."
81 option for allowed values.
82 -T src_cache
84 in contrast specifies the cache mode that should be used with the
85 source file(s).
86 Parameters to snapshot subcommand:
88 snapshot
90 is the name of the snapshot to create, apply or delete
91 -a applies a snapshot (revert disk to saved state)
93 -c creates a snapshot
95 -d deletes a snapshot
97 -l lists all snapshots in the given image
99 Parameters to compare subcommand:
101 -f First image format
103 -F Second image format
105 -s Strict mode - fail on on different image size or sector allocation
107 Command description:
109 check [-f fmt] [--output=ofmt] [-r [leaks | all]] [-T src_cache]
111 filename
112 Perform a consistency check on the disk image filename. The command
113 can output in the format ofmt which is either "human" or "json".
114 If "-r" is specified, qemu-img tries to repair any inconsistencies
116 found during the check. "-r leaks" repairs only cluster leaks,
117 whereas "-r all" fixes all kinds of errors, with a higher risk of
118 choosing the wrong fix or hiding corruption that has already
119 occured.
120 Only the formats "qcow2", "qed" and "vdi" support consistency
122 checks.
123 In case the image does not have any inconsistencies, check exits
125 with 0. Other exit codes indicate the kind of inconsistency found
126 or if another error occurred. The following table summarizes all
127 exit codes of the check subcommand:
128 0 Check completed, the image is (now) consistent
130 1 Check not completed because of internal errors
132 2 Check completed, image is corrupted
134 3 Check completed, image has leaked clusters, but is not
136 corrupted
137 63 Checks are not supported by the image format
139 If "-r" is specified, exit codes representing the image state refer
141 to the state after (the attempt at) repairing it. That is, a
142 successful "-r all" will yield the exit code 0, independently of
143 the image state before.
144 create [-f fmt] [-o options] filename [size]
146 Create the new disk image filename of size size and format fmt.
147 Depending on the file format, you can add one or more options that
148 enable additional features of this format.
149 If the option backing_file is specified, then the image will record
151 only the differences from backing_file. No size needs to be
152 specified in this case. backing_file will never be modified unless
153 you use the "commit" monitor command (or qemu-img commit).
154 The size can also be specified using the size option with "-o", it
156 doesn't need to be specified separately in this case.
157 commit [-f fmt] [-t cache] filename
159 Commit the changes recorded in filename in its base image.
160 compare [-f fmt] [-F fmt] [-T src_cache] [-p] [-s] filename1 filename2
162 Check if two images have the same content. You can compare images
163 with different format or settings.
164 The format is probed unless you specify it by -f (used for
166 filename1) and/or -F (used for filename2) option.
167 By default, images with different size are considered identical if
169 the larger image contains only unallocated and/or zeroed sectors in
170 the area after the end of the other image. In addition, if any
171 sector is not allocated in one image and contains only zero bytes
172 in the second one, it is evaluated as equal. You can use Strict
173 mode by specifying the -s option. When compare runs in Strict mode,
174 it fails in case image size differs or a sector is allocated in one
175 image and is not allocated in the second one.
176 By default, compare prints out a result message. This message
178 displays information that both images are same or the position of
179 the first different byte. In addition, result message can report
180 different image size in case Strict mode is used.
181 Compare exits with 0 in case the images are equal and with 1 in
183 case the images differ. Other exit codes mean an error occurred
184 during execution and standard error output should contain an error
185 message. The following table sumarizes all exit codes of the
186 compare subcommand:
187 0 Images are identical
189 1 Images differ
191 2 Error on opening an image
193 3 Error on checking a sector allocation
195 4 Error on reading data
197 convert [-c] [-p] [-f fmt] [-t cache] [-T src_cache] [-O output_fmt]
199 [-o options] [-S sparse_size] filename [filename2 [...]]
200 output_filename
201 Convert the disk image filename to disk image output_filename using
202 format output_fmt. It can be optionally compressed ("-c" option) or
203 use any format specific options like encryption ("-o" option).
204 Only the formats "qcow" and "qcow2" support compression. The
206 compression is read-only. It means that if a compressed sector is
207 rewritten, then it is rewritten as uncompressed data.
208 Image conversion is also useful to get smaller image when using a
210 growable format such as "qcow" or "cow": the empty sectors are
211 detected and suppressed from the destination image.
212 sparse_size indicates the consecutive number of bytes (defaults to
214 4k) that must contain only zeros for qemu-img to create a sparse
215 image during conversion. If sparse_size is 0, the source will not
216 be scanned for unallocated or zero sectors, and the destination
217 image will always be fully allocated.
218 You can use the backing_file option to force the output image to be
220 created as a copy on write image of the specified base image; the
221 backing_file should have the same content as the input's base
222 image, however the path, image format, etc may differ.
223 info [-f fmt] [--output=ofmt] filename
225 Give information about the disk image filename. Use it in
226 particular to know the size reserved on disk which can be different
227 from the displayed size. If VM snapshots are stored in the disk
228 image, they are displayed too. The command can output in the format
229 ofmt which is either "human" or "json".
230 map [-f fmt] [--output=ofmt] filename
232 Dump the metadata of image filename and its backing file chain. In
233 particular, this commands dumps the allocation state of every
234 sector of filename, together with the topmost file that allocates
235 it in the backing file chain.
236 Two option formats are possible. The default format ("human") only
238 dumps known-nonzero areas of the file. Known-zero parts of the
239 file are omitted altogether, and likewise for parts that are not
240 allocated throughout the chain. qemu-img output will identify a
241 file from where the data can be read, and the offset in the file.
242 Each line will include four fields, the first three of which are
243 hexadecimal numbers. For example the first line of:
244 Offset Length Mapped to File
246 0 0x20000 0x50000 /tmp/overlay.qcow2
247 0x100000 0x10000 0x95380000 /tmp/backing.qcow2
248 means that 0x20000 (131072) bytes starting at offset 0 in the image
250 are available in /tmp/overlay.qcow2 (opened in "raw" format)
251 starting at offset 0x50000 (327680). Data that is compressed,
252 encrypted, or otherwise not available in raw format will cause an
253 error if "human" format is in use. Note that file names can
254 include newlines, thus it is not safe to parse this output format
255 in scripts.
256 The alternative format "json" will return an array of dictionaries
258 in JSON format. It will include similar information in the
259 "start", "length", "offset" fields; it will also include other more
260 specific information:
261 - whether the sectors contain actual data or not (boolean field
263 "data"; if false, the sectors are either unallocated or stored
264 as optimized all-zero clusters);
265 - whether the data is known to read as zero (boolean field
267 "zero");
268 - in order to make the output shorter, the target file is
270 expressed as a "depth"; for example, a depth of 2 refers to the
271 backing file of the backing file of filename.
272 In JSON format, the "offset" field is optional; it is absent in
274 cases where "human" format would omit the entry or exit with an
275 error. If "data" is false and the "offset" field is present, the
276 corresponding sectors in the file are not yet in use, but they are
277 preallocated.
278 For more information, consult include/block/block.h in QEMU's
280 source code.
281 snapshot [-l | -a snapshot | -c snapshot | -d snapshot ] filename
283 List, apply, create or delete snapshots in image filename.
284 rebase [-f fmt] [-t cache] [-T src_cache] [-p] [-u] -b backing_file [-F
286 backing_fmt] filename
287 Changes the backing file of an image. Only the formats "qcow2" and
288 "qed" support changing the backing file.
289 The backing file is changed to backing_file and (if the image
291 format of filename supports this) the backing file format is
292 changed to backing_fmt. If backing_file is specified as "" (the
293 empty string), then the image is rebased onto no backing file (i.e.
294 it will exist independently of any backing file).
295 cache specifies the cache mode to be used for filename, whereas
297 src_cache specifies the cache mode for reading the new backing
298 file.
299 There are two different modes in which "rebase" can operate:
301 Safe mode
303 This is the default mode and performs a real rebase operation.
304 The new backing file may differ from the old one and qemu-img
305 rebase will take care of keeping the guest-visible content of
306 filename unchanged.
307 In order to achieve this, any clusters that differ between
309 backing_file and the old backing file of filename are merged
310 into filename before actually changing the backing file.
311 Note that the safe mode is an expensive operation, comparable
313 to converting an image. It only works if the old backing file
314 still exists.
315 Unsafe mode
317 qemu-img uses the unsafe mode if "-u" is specified. In this
318 mode, only the backing file name and format of filename is
319 changed without any checks on the file contents. The user must
320 take care of specifying the correct new backing file, or the
321 guest-visible content of the image will be corrupted.
322 This mode is useful for renaming or moving the backing file to
324 somewhere else. It can be used without an accessible old
325 backing file, i.e. you can use it to fix an image whose backing
326 file has already been moved/renamed.
327 resize filename [+ | -]size
329 Change the disk image as if it had been created with size.
330 Before using this command to shrink a disk image, you MUST use file
332 system and partitioning tools inside the VM to reduce allocated
333 file systems and partition sizes accordingly. Failure to do so
334 will result in data loss!
335 After using this command to grow a disk image, you must use file
337 system and partitioning tools inside the VM to actually begin using
338 the new space on the device.
339 Supported image file formats:
341 raw Raw disk image format (default). This format has the advantage of
343 being simple and easily exportable to all other emulators. If your
344 file system supports holes (for example in ext2 or ext3 on Linux or
345 NTFS on Windows), then only the written sectors will reserve space.
346 Use "qemu-img info" to know the real size used by the image or "ls
347 -ls" on Unix/Linux.
348 Supported options:
350 "preallocation"
352 Preallocation mode (allowed values: "off", "falloc", "full").
353 "falloc" mode preallocates space for image by calling
354 posix_fallocate(). "full" mode preallocates space for image by
355 writing zeros to underlying storage.
356 qcow2
358 QEMU image format, the most versatile format. Use it to have
359 smaller images (useful if your filesystem does not supports holes,
360 for example on Windows), optional AES encryption, zlib based
361 compression and support of multiple VM snapshots.
362 Supported options:
364 "backing_file"
366 File name of a base image (see create subcommand)
367 "backing_fmt"
369 Image format of the base image
370 "encryption"
372 If this option is set to "on", the image is encrypted.
373 Encryption uses the AES format which is very secure (128 bit
375 keys). Use a long password (16 characters) to get maximum
376 protection.
377 "cluster_size"
379 Changes the qcow2 cluster size (must be between 512 and 2M).
380 Smaller cluster sizes can improve the image file size whereas
381 larger cluster sizes generally provide better performance.
382 "preallocation"
384 Preallocation mode (allowed values: "off", "metadata",
385 "falloc", "full"). An image with preallocated metadata is
386 initially larger but can improve performance when the image
387 needs to grow. "falloc" and "full" preallocations are like the
388 same options of "raw" format, but sets up metadata also.
389 qcow
391 Old QEMU image format. Left for compatibility.
392 Supported options:
394 "backing_file"
396 File name of a base image (see create subcommand)
397 "encryption"
399 If this option is set to "on", the image is encrypted.
400 cow User Mode Linux Copy On Write image format. Used to be the only
402 growable image format in QEMU. It is supported only for
403 compatibility with previous versions. It does not work on win32.
404 vdi VirtualBox 1.1 compatible image format.
406 vmdk
408 VMware 3 and 4 compatible image format.
409 Supported options:
411 "backing_fmt"
413 Image format of the base image
414 "compat6"
416 Create a VMDK version 6 image (instead of version 4)
417 vpc VirtualPC compatible image format (VHD).
419 vhdx
421 Hyper-V compatible image format (VHDX).
422 cloop
424 Linux Compressed Loop image, useful only to reuse directly
425 compressed CD-ROM images present for example in the Knoppix CD-
426 ROMs.
427
429 The HTML documentation of QEMU for more precise information and Linux
430 user mode emulator invocation.
431
433 Fabrice Bellard
434 2019-05-14 QEMU-IMG(1)