QMP: QMP/ -> docs/qmp/
[qemu/ar7.git] / qemu-img.texi
blob768054e9008d93bf0e8420bfbf02516dd8eab0f7
1 @example
2 @c man begin SYNOPSIS
3 usage: qemu-img command [command options]
4 @c man end
5 @end example
7 @c man begin DESCRIPTION
8 qemu-img allows you to create, convert and modify images offline. It can handle
9 all image formats supported by QEMU.
11 @b{Warning:} Never use qemu-img to modify images in use by a running virtual
12 machine or any other process; this may destroy the image. Also, be aware that
13 querying an image that is being modified by another process may encounter
14 inconsistent state.
15 @c man end
17 @c man begin OPTIONS
19 The following commands are supported:
21 @include qemu-img-cmds.texi
23 Command parameters:
24 @table @var
25 @item filename
26  is a disk image filename
27 @item fmt
28 is the disk image format. It is guessed automatically in most cases. See below
29 for a description of the supported disk formats.
31 @item --backing-chain
32 will enumerate information about backing files in a disk image chain. Refer
33 below for further description.
35 @item size
36 is the disk image size in bytes. Optional suffixes @code{k} or @code{K}
37 (kilobyte, 1024) @code{M} (megabyte, 1024k) and @code{G} (gigabyte, 1024M)
38 and T (terabyte, 1024G) are supported.  @code{b} is ignored.
40 @item output_filename
41 is the destination disk image filename
43 @item output_fmt
44  is the destination format
45 @item options
46 is a comma separated list of format specific options in a
47 name=value format. Use @code{-o ?} for an overview of the options supported
48 by the used format or see the format descriptions below for details.
51 @item -c
52 indicates that target image must be compressed (qcow format only)
53 @item -h
54 with or without a command shows help and lists the supported formats
55 @item -p
56 display progress bar (convert and rebase commands only)
57 @item -q
58 Quiet mode - do not print any output (except errors). There's no progress bar
59 in case both @var{-q} and @var{-p} options are used.
60 @item -S @var{size}
61 indicates the consecutive number of bytes that must contain only zeros
62 for qemu-img to create a sparse image during conversion. This value is rounded
63 down to the nearest 512 bytes. You may use the common size suffixes like
64 @code{k} for kilobytes.
65 @item -t @var{cache}
66 specifies the cache mode that should be used with the (destination) file. See
67 the documentation of the emulator's @code{-drive cache=...} option for allowed
68 values.
69 @end table
71 Parameters to snapshot subcommand:
73 @table @option
75 @item snapshot
76 is the name of the snapshot to create, apply or delete
77 @item -a
78 applies a snapshot (revert disk to saved state)
79 @item -c
80 creates a snapshot
81 @item -d
82 deletes a snapshot
83 @item -l
84 lists all snapshots in the given image
85 @end table
87 Parameters to compare subcommand:
89 @table @option
91 @item -f
92 First image format
93 @item -F
94 Second image format
95 @item -s
96 Strict mode - fail on on different image size or sector allocation
97 @end table
99 Parameters to convert subcommand:
101 @table @option
103 @item -n
104 Skip the creation of the target volume
105 @end table
107 Command description:
109 @table @option
110 @item check [-f @var{fmt}] [--output=@var{ofmt}] [-r [leaks | all]] @var{filename}
112 Perform a consistency check on the disk image @var{filename}. The command can
113 output in the format @var{ofmt} which is either @code{human} or @code{json}.
115 If @code{-r} is specified, qemu-img tries to repair any inconsistencies found
116 during the check. @code{-r leaks} repairs only cluster leaks, whereas
117 @code{-r all} fixes all kinds of errors, with a higher risk of choosing the
118 wrong fix or hiding corruption that has already occurred.
120 Only the formats @code{qcow2}, @code{qed} and @code{vdi} support
121 consistency checks.
123 @item create [-f @var{fmt}] [-o @var{options}] @var{filename} [@var{size}]
125 Create the new disk image @var{filename} of size @var{size} and format
126 @var{fmt}. Depending on the file format, you can add one or more @var{options}
127 that enable additional features of this format.
129 If the option @var{backing_file} is specified, then the image will record
130 only the differences from @var{backing_file}. No size needs to be specified in
131 this case. @var{backing_file} will never be modified unless you use the
132 @code{commit} monitor command (or qemu-img commit).
134 The size can also be specified using the @var{size} option with @code{-o},
135 it doesn't need to be specified separately in this case.
137 @item commit [-f @var{fmt}] [-t @var{cache}] @var{filename}
139 Commit the changes recorded in @var{filename} in its base image.
141 @item compare [-f @var{fmt}] [-F @var{fmt}] [-p] [-s] [-q] @var{filename1} @var{filename2}
143 Check if two images have the same content. You can compare images with
144 different format or settings.
146 The format is probed unless you specify it by @var{-f} (used for
147 @var{filename1}) and/or @var{-F} (used for @var{filename2}) option.
149 By default, images with different size are considered identical if the larger
150 image contains only unallocated and/or zeroed sectors in the area after the end
151 of the other image. In addition, if any sector is not allocated in one image
152 and contains only zero bytes in the second one, it is evaluated as equal. You
153 can use Strict mode by specifying the @var{-s} option. When compare runs in
154 Strict mode, it fails in case image size differs or a sector is allocated in
155 one image and is not allocated in the second one.
157 By default, compare prints out a result message. This message displays
158 information that both images are same or the position of the first different
159 byte. In addition, result message can report different image size in case
160 Strict mode is used.
162 Compare exits with @code{0} in case the images are equal and with @code{1}
163 in case the images differ. Other exit codes mean an error occurred during
164 execution and standard error output should contain an error message.
165 The following table sumarizes all exit codes of the compare subcommand:
167 @table @option
169 @item 0
170 Images are identical
171 @item 1
172 Images differ
173 @item 2
174 Error on opening an image
175 @item 3
176 Error on checking a sector allocation
177 @item 4
178 Error on reading data
180 @end table
182 @item convert [-c] [-p] [-n] [-f @var{fmt}] [-t @var{cache}] [-O @var{output_fmt}] [-o @var{options}] [-s @var{snapshot_name}] [-S @var{sparse_size}] @var{filename} [@var{filename2} [...]] @var{output_filename}
184 Convert the disk image @var{filename} or a snapshot @var{snapshot_name} to disk image @var{output_filename}
185 using format @var{output_fmt}. It can be optionally compressed (@code{-c}
186 option) or use any format specific options like encryption (@code{-o} option).
188 Only the formats @code{qcow} and @code{qcow2} support compression. The
189 compression is read-only. It means that if a compressed sector is
190 rewritten, then it is rewritten as uncompressed data.
192 Image conversion is also useful to get smaller image when using a
193 growable format such as @code{qcow} or @code{cow}: the empty sectors
194 are detected and suppressed from the destination image.
196 You can use the @var{backing_file} option to force the output image to be
197 created as a copy on write image of the specified base image; the
198 @var{backing_file} should have the same content as the input's base image,
199 however the path, image format, etc may differ.
201 If the @code{-n} option is specified, the target volume creation will be
202 skipped. This is useful for formats such as @code{rbd} if the target
203 volume has already been created with site specific options that cannot
204 be supplied through qemu-img.
206 @item info [-f @var{fmt}] [--output=@var{ofmt}] [--backing-chain] @var{filename}
208 Give information about the disk image @var{filename}. Use it in
209 particular to know the size reserved on disk which can be different
210 from the displayed size. If VM snapshots are stored in the disk image,
211 they are displayed too. The command can output in the format @var{ofmt}
212 which is either @code{human} or @code{json}.
214 If a disk image has a backing file chain, information about each disk image in
215 the chain can be recursively enumerated by using the option @code{--backing-chain}.
217 For instance, if you have an image chain like:
219 @example
220 base.qcow2 <- snap1.qcow2 <- snap2.qcow2
221 @end example
223 To enumerate information about each disk image in the above chain, starting from top to base, do:
225 @example
226 qemu-img info --backing-chain snap2.qcow2
227 @end example
229 @item map [-f @var{fmt}] [--output=@var{ofmt}] @var{filename}
231 Dump the metadata of image @var{filename} and its backing file chain.
232 In particular, this commands dumps the allocation state of every sector
233 of @var{filename}, together with the topmost file that allocates it in
234 the backing file chain.
236 Two option formats are possible.  The default format (@code{human})
237 only dumps known-nonzero areas of the file.  Known-zero parts of the
238 file are omitted altogether, and likewise for parts that are not allocated
239 throughout the chain.  @command{qemu-img} output will identify a file
240 from where the data can be read, and the offset in the file.  Each line
241 will include four fields, the first three of which are hexadecimal
242 numbers.  For example the first line of:
243 @example
244 Offset          Length          Mapped to       File
245 0               0x20000         0x50000         /tmp/overlay.qcow2
246 0x100000        0x10000         0x95380000      /tmp/backing.qcow2
247 @end example
248 @noindent
249 means that 0x20000 (131072) bytes starting at offset 0 in the image are
250 available in /tmp/overlay.qcow2 (opened in @code{raw} format) starting
251 at offset 0x50000 (327680).  Data that is compressed, encrypted, or
252 otherwise not available in raw format will cause an error if @code{human}
253 format is in use.  Note that file names can include newlines, thus it is
254 not safe to parse this output format in scripts.
256 The alternative format @code{json} will return an array of dictionaries
257 in JSON format.  It will include similar information in
258 the @code{start}, @code{length}, @code{offset} fields;
259 it will also include other more specific information:
260 @itemize @minus
261 @item
262 whether the sectors contain actual data or not (boolean field @code{data};
263 if false, the sectors are either unallocated or stored as optimized
264 all-zero clusters);
266 @item
267 whether the data is known to read as zero (boolean field @code{zero});
269 @item
270 in order to make the output shorter, the target file is expressed as
271 a @code{depth}; for example, a depth of 2 refers to the backing file
272 of the backing file of @var{filename}.
273 @end itemize
275 In JSON format, the @code{offset} field is optional; it is absent in
276 cases where @code{human} format would omit the entry or exit with an error.
277 If @code{data} is false and the @code{offset} field is present, the
278 corresponding sectors in the file are not yet in use, but they are
279 preallocated.
281 For more information, consult @file{include/block/block.h} in QEMU's
282 source code.
284 @item snapshot [-l | -a @var{snapshot} | -c @var{snapshot} | -d @var{snapshot} ] @var{filename}
286 List, apply, create or delete snapshots in image @var{filename}.
288 @item rebase [-f @var{fmt}] [-t @var{cache}] [-p] [-u] -b @var{backing_file} [-F @var{backing_fmt}] @var{filename}
290 Changes the backing file of an image. Only the formats @code{qcow2} and
291 @code{qed} support changing the backing file.
293 The backing file is changed to @var{backing_file} and (if the image format of
294 @var{filename} supports this) the backing file format is changed to
295 @var{backing_fmt}. If @var{backing_file} is specified as ``'' (the empty
296 string), then the image is rebased onto no backing file (i.e. it will exist
297 independently of any backing file).
299 There are two different modes in which @code{rebase} can operate:
300 @table @option
301 @item Safe mode
302 This is the default mode and performs a real rebase operation. The new backing
303 file may differ from the old one and qemu-img rebase will take care of keeping
304 the guest-visible content of @var{filename} unchanged.
306 In order to achieve this, any clusters that differ between @var{backing_file}
307 and the old backing file of @var{filename} are merged into @var{filename}
308 before actually changing the backing file.
310 Note that the safe mode is an expensive operation, comparable to converting
311 an image. It only works if the old backing file still exists.
313 @item Unsafe mode
314 qemu-img uses the unsafe mode if @code{-u} is specified. In this mode, only the
315 backing file name and format of @var{filename} is changed without any checks
316 on the file contents. The user must take care of specifying the correct new
317 backing file, or the guest-visible content of the image will be corrupted.
319 This mode is useful for renaming or moving the backing file to somewhere else.
320 It can be used without an accessible old backing file, i.e. you can use it to
321 fix an image whose backing file has already been moved/renamed.
322 @end table
324 You can use @code{rebase} to perform a ``diff'' operation on two
325 disk images.  This can be useful when you have copied or cloned
326 a guest, and you want to get back to a thin image on top of a
327 template or base image.
329 Say that @code{base.img} has been cloned as @code{modified.img} by
330 copying it, and that the @code{modified.img} guest has run so there
331 are now some changes compared to @code{base.img}.  To construct a thin
332 image called @code{diff.qcow2} that contains just the differences, do:
334 @example
335 qemu-img create -f qcow2 -b modified.img diff.qcow2
336 qemu-img rebase -b base.img diff.qcow2
337 @end example
339 At this point, @code{modified.img} can be discarded, since
340 @code{base.img + diff.qcow2} contains the same information.
342 @item resize @var{filename} [+ | -]@var{size}
344 Change the disk image as if it had been created with @var{size}.
346 Before using this command to shrink a disk image, you MUST use file system and
347 partitioning tools inside the VM to reduce allocated file systems and partition
348 sizes accordingly.  Failure to do so will result in data loss!
350 After using this command to grow a disk image, you must use file system and
351 partitioning tools inside the VM to actually begin using the new space on the
352 device.
354 @item amend [-f @var{fmt}] -o @var{options} @var{filename}
356 Amends the image format specific @var{options} for the image file
357 @var{filename}. Not all file formats support this operation.
358 @end table
359 @c man end
361 @ignore
362 @c man begin NOTES
363 Supported image file formats:
365 @table @option
366 @item raw
368 Raw disk image format (default). This format has the advantage of
369 being simple and easily exportable to all other emulators. If your
370 file system supports @emph{holes} (for example in ext2 or ext3 on
371 Linux or NTFS on Windows), then only the written sectors will reserve
372 space. Use @code{qemu-img info} to know the real size used by the
373 image or @code{ls -ls} on Unix/Linux.
375 @item qcow2
376 QEMU image format, the most versatile format. Use it to have smaller
377 images (useful if your filesystem does not supports holes, for example
378 on Windows), optional AES encryption, zlib based compression and
379 support of multiple VM snapshots.
381 Supported options:
382 @table @code
383 @item compat
384 Determines the qcow2 version to use. @code{compat=0.10} uses the traditional
385 image format that can be read by any QEMU since 0.10 (this is the default).
386 @code{compat=1.1} enables image format extensions that only QEMU 1.1 and
387 newer understand. Amongst others, this includes zero clusters, which allow
388 efficient copy-on-read for sparse images.
390 @item backing_file
391 File name of a base image (see @option{create} subcommand)
392 @item backing_fmt
393 Image format of the base image
394 @item encryption
395 If this option is set to @code{on}, the image is encrypted.
397 Encryption uses the AES format which is very secure (128 bit keys). Use
398 a long password (16 characters) to get maximum protection.
400 @item cluster_size
401 Changes the qcow2 cluster size (must be between 512 and 2M). Smaller cluster
402 sizes can improve the image file size whereas larger cluster sizes generally
403 provide better performance.
405 @item preallocation
406 Preallocation mode (allowed values: off, metadata). An image with preallocated
407 metadata is initially larger but can improve performance when the image needs
408 to grow.
410 @item lazy_refcounts
411 If this option is set to @code{on}, reference count updates are postponed with
412 the goal of avoiding metadata I/O and improving performance. This is
413 particularly interesting with @option{cache=writethrough} which doesn't batch
414 metadata updates. The tradeoff is that after a host crash, the reference count
415 tables must be rebuilt, i.e. on the next open an (automatic) @code{qemu-img
416 check -r all} is required, which may take some time.
418 This option can only be enabled if @code{compat=1.1} is specified.
420 @end table
422 @item Other
423 QEMU also supports various other image file formats for compatibility with
424 older QEMU versions or other hypervisors, including VMDK, VDI, VHD (vpc), qcow1
425 and QED. For a full list of supported formats see @code{qemu-img --help}.
426 For a more detailed description of these formats, see the QEMU Emulation User
427 Documentation.
429 The main purpose of the block drivers for these formats is image conversion.
430 For running VMs, it is recommended to convert the disk images to either raw or
431 qcow2 in order to achieve good performance.
432 @end table
435 @c man end
437 @setfilename qemu-img
438 @settitle QEMU disk image utility
440 @c man begin SEEALSO
441 The HTML documentation of QEMU for more precise information and Linux
442 user mode emulator invocation.
443 @c man end
445 @c man begin AUTHOR
446 Fabrice Bellard
447 @c man end
449 @end ignore